pubsub: add documentation about message extension
@@ -93,31 +93,29 @@ overridden. This section describes the tradeoffs that should be considered
when overriding the defaults.
Behind the scenes, each message returned by the Pub/Sub server has an
-associated lease, known as an "ACK deadline".
-Unless a message is acknowledged within the ACK deadline, or the client requests that
-the ACK deadline be extended, the message will become elegible for redelivery.
-As a convenience, the pubsub package will automatically extend deadlines until
+associated lease, known as an "ACK deadline". Unless a message is
+acknowledged within the ACK deadline, or the client requests that
+the ACK deadline be extended, the message will become eligible for redelivery.
+
+As a convenience, the pubsub client will automatically extend deadlines until
either:
* Message.Ack or Message.Nack is called, or
- * the "MaxExtension" period elapses from the time the message is fetched from the server.
-
-The initial ACK deadline given to each messages defaults to 10 seconds, but may
-be overridden during subscription creation. Selecting an ACK deadline is a
-tradeoff between message redelivery latency and RPC volume. If the pubsub
-package fails to acknowledge or extend a message (e.g. due to unexpected
-termination of the process), a shorter ACK deadline will generally result in
-faster message redelivery by the Pub/Sub system. However, a short ACK deadline
-may also increase the number of deadline extension RPCs that the pubsub package
-sends to the server.
-
-The default max extension period is DefaultReceiveSettings.MaxExtension, and can
-be overridden by setting Subscription.ReceiveSettings.MaxExtension. Selecting a
-max extension period is a tradeoff between the speed at which client code must
-process messages, and the redelivery delay if messages fail to be acknowledged
-(e.g. because client code neglects to do so). Using a large MaxExtension
-increases the available time for client code to process messages. However, if
-the client code neglects to call Message.Ack/Nack, a large MaxExtension will
-increase the delay before the message is redelivered.
+ * The "MaxExtension" period elapses from the time the message is fetched from the server.
+
+ACK deadlines are extended periodically by the client. The initial ACK
+deadline given to messages is 10s. The period between extensions, as well as the
+length of the extension, automatically adjust depending on the time it takes to ack
+messages, up to 10m. This has the effect that subscribers that process messages
+quickly have their message ack deadlines extended for a short amount, whereas
+subscribers that process message slowly have their message ack deadlines extended
+for a large amount. The net effect is fewer RPCs sent from the client library.
+
+For example, consider a subscriber that takes 3 minutes to process each message.
+Since the library has already recorded several 3 minute "time to ack"s in a
+percentile distribution, future message extensions are sent with a value of 3
+minutes, every 3 minutes. Suppose the application crashes 5 seconds after the
+library sends such an extension: the Pub/Sub server would wait the remaining
+2m55s before re-sending the messages out to other subscribers.
Slow Message Processing
