Skip to content
Permalink
Browse files
docs: add flow control section to publish overview (#129)
* 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 committed Jul 10, 2020
1 parent 04e261c commit acc19eb048eef067d9818ef3e310b165d9c6307e
Showing with 36 additions and 0 deletions.
  1. +36 −0 docs/publisher/index.rst
@@ -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
-------------

0 comments on commit acc19eb

Please sign in to comment.