pubsub: poor documentation regarding flow control ReceiveSettings

[mc0]

Client

PubSub

Issue

Prior to 1.9, the behavior of the PubSub client was that MaxOutstandingMessages and MaxOutstandingBytes were ignored if Synchronous was changed to true.

The behavior changed such that the client passes server-side flow control configuration[0] to control the messages received. This change fixes some of the necessity of Synchronous: true, but the documentation implies that the behavior is much different.

Specifically, these sections:

Note: This uses pubsub's streaming pull feature. This feature properties that may be surprising. Please take a look at https://cloud.google.com/pubsub/docs/pull#streamingpull for more details on how streaming pull behaves compared to the synchronous pull method.

In contrast, when Synchronous is false, more than MaxOutstandingMessages may have been received from the service and in memory before being processed.) MaxOutstandingBytes still refers to the total bytes processed, rather than in memory.

Additionally, some of the official documentation referenced (cloud.google.com/pubsub/docs) is a bit misleading (since not all clients use server-side flow control) but the documentation for this library does not note this discrepancy.

Thanks!

0: https://cloud.google.com/pubsub/docs/reference/rpc/google.pubsub.v1#streamingpullrequest

Additional context

PR for the 1.9 change: #3154

Prior discussion: #1485 which points to https://cloud.google.com/pubsub/docs/pull#streamingpull_dealing_with_large_backlogs_of_small_messages

[hongalex]

I agree that some of these information is slightly out of date. The docs should be updated to reflect that

1. Server-side flow control mitigates issues with a large backlog of small messages exceeding MaxOutstandingMessages
2. Synchronous mode still uses client side flow control.

Does that sound right to you?

[mc0]

Absolutely. For a coworker and I, the knowledge of the past behavior made the stale library documentation seem to imply more than it did (in conjunction with the stale GCP documentation).

Thanks @hongalex.

[hongalex]

Prior to 1.9, the behavior of the PubSub client was that MaxOutstandingMessages and MaxOutstandingBytes were ignored if Synchronous was changed to true.

Revisiting this, I actually failed to point out that this isn't true. Flow control was always respected, regardless of whether synchronous is true or not.

However, the client library docs still need to be updated since the information around MaxOutstandingMessages is no longer true.