Skip to content

Commit

Permalink
docs: add flow control section to publish overview (#129)
Browse files Browse the repository at this point in the history
* docs: add flow control section to publish overview

* Explain options for limit exceeded behavior

* Omit a sentence that might cause confusion.
  • Loading branch information
plamut authored Jul 10, 2020
1 parent 04e261c commit acc19eb
Showing 1 changed file with 36 additions and 0 deletions.
36 changes: 36 additions & 0 deletions docs/publisher/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,42 @@ You can also attach a callback to the future:
future.add_done_callback(callback)
Publish Flow Control
--------------------

If publishing large amounts of messages or very large messages in quick
succession, some of the publish requests might time out, especially if the
bandwidth available is limited. To mitigate this the client can be
configured with custom :class:`~.pubsub_v1.types.PublishFlowControl` settings.

You can configure the maximum desired number of messages and their maximum total
size, as well as the action that should be taken when the threshold is reached.

.. code-block:: python
from google.cloud import pubsub_v1
client = pubsub_v1.PublisherClient(
publisher_options=pubsub_v1.types.PublisherOptions(
flow_control=pubsub_v1.types.PublishFlowControl(
message_limit=500,
byte_limit=2 * 1024 * 1024,
limit_exceeded_behavior=pubsub_v1.types.LimitExceededBehavior.BLOCK,
),
),
)
The action to be taken on overflow can be one of the following:

* :attr:`~.pubsub_v1.types.LimitExceededBehavior.IGNORE` (default): Ignore the
overflow and continue publishing the messages as normal.
* :attr:`~.pubsub_v1.types.LimitExceededBehavior.ERROR`: Raise
:exc:`~.pubsub_v1.publisher.exceptions.FlowControlLimitError` and reject the message.
* :attr:`~.pubsub_v1.types.LimitExceededBehavior.BLOCK`: Temporarily block in the
:meth:`~.pubsub_v1.publisher.client.Client.publish` method until there is
enough capacity available.


API Reference
-------------

Expand Down

0 comments on commit acc19eb

Please sign in to comment.