Google Cloud Pub/Sub C++ Client  2.5.0
A C++ Client Library for Google Cloud Pub/Sub
options.h
Go to the documentation of this file.
1 // Copyright 2021 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_OPTIONS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_OPTIONS_H
17 
18 /**
19  * @file
20  *
21  * This file defines options to be used with instances of
22  * `google::cloud::Options`. By convention options are named with an "Option"
23  * suffix. As the name would imply, all options are optional, and leaving them
24  * unset will result in a reasonable default being chosen.
25  *
26  * Not all options are meaningful to all functions that accept a
27  * `google::cloud::Options` instance. Each function that accepts a
28  * `google::cloud::Options` should document which options it expects. This is
29  * typically done by indicating lists of options using "OptionList" aliases.
30  * For example, a function may indicate that users may set any option in
31  * `PublisherOptionList`.
32  *
33  * @note Unrecognized options are allowed and will be ignored. To debug issues
34  * with options set `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment
35  * and unexpected options will be logged.
36  *
37  * @see `google::cloud::CommonOptionList`
38  * @see `google::cloud::GrpcOptionList`
39  */
40 
41 #include "google/cloud/pubsub/backoff_policy.h"
42 #include "google/cloud/pubsub/retry_policy.h"
43 #include "google/cloud/pubsub/subscription.h"
44 #include "google/cloud/pubsub/version.h"
45 #include "google/cloud/options.h"
46 #include <chrono>
47 
48 namespace google {
49 namespace cloud {
50 namespace pubsub {
52 
53 /**
54  * The retry policy
55  *
56  * @ingroup pubsub-options
57  */
59  using Type = std::shared_ptr<pubsub::RetryPolicy>;
60 };
61 
62 /**
63  * The backoff policy
64  *
65  * @ingroup pubsub-options
66  */
68  using Type = std::shared_ptr<pubsub::BackoffPolicy>;
69 };
70 
71 /// The list of all "policy" options.
72 using PolicyOptionList = OptionList<RetryPolicyOption, BackoffPolicyOption>;
73 
74 /**
75  * The maximum hold time for the messages.
76  *
77  * @note The implementation depends on the granularity of your OS timers. It is
78  * possible that messages are held for slightly longer times than the value
79  * set here.
80  *
81  * @note The first message in a batch starts the hold time counter. New
82  * messages do not extend the life of the batch. For example, if you have
83  * set the holding time to 10 milliseconds, start a batch with message 1,
84  * and publish a second message 5 milliseconds later, the second message
85  * will be flushed approximately 5 milliseconds after it is published.
86  *
87  * @ingroup pubsub-options
88  */
90  using Type = std::chrono::microseconds;
91 };
92 
93 /**
94  * The maximum number of messages in a batch.
95  *
96  * @note Application developers should keep in mind that Cloud Pub/Sub
97  * sets [limits][pubsub-quota-link] on the size of a batch (1,000 messages)
98  * The library makes no attempt to validate the value provided in this
99  * option.
100  *
101  * [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
102  *
103  * @ingroup pubsub-options
104  */
106  using Type = std::size_t;
107 };
108 
109 /**
110  * The maximum size for the messages in a batch.
111  *
112  * @note Application developers should keep in mind that Cloud Pub/Sub
113  * sets [limits][pubsub-quota-link] on the size of a batch (10MB). The
114  * library makes no attempt to validate the value provided in this
115  * option.
116  *
117  * [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
118  *
119  * @ingroup pubsub-options
120  */
122  using Type = std::size_t;
123 };
124 
125 /**
126  * The maximum number of pending messages.
127  *
128  * After a publisher flushes a batch of messages the batch is (obviously) not
129  * received immediately by the service. While the batch remains pending it
130  * potentially consumes memory resources in the client (and/or the service).
131  *
132  * Some applications may have constraints on the number of bytes and/or
133  * messages they can tolerate in this pending state, and may prefer to block
134  * or reject messages.
135  *
136  * @ingroup pubsub-options
137  */
139  using Type = std::size_t;
140 };
141 
142 /**
143  * The maximum size for pending messages.
144  *
145  * After a publisher flushes a batch of messages the batch is (obviously) not
146  * received immediately by the service. While the batch remains pending it
147  * potentially consumes memory resources in the client (and/or the service).
148  *
149  * Some applications may have constraints on the number of bytes and/or
150  * messages they can tolerate in this pending state, and may prefer to block
151  * or reject messages.
152  *
153  * @ingroup pubsub-options
154  */
156  using Type = std::size_t;
157 };
158 
159 /**
160  * Publisher message ordering.
161  *
162  * To guarantee messages are received by the service in the same order that
163  * the application gives them to a publisher, the client library needs to wait
164  * until a batch of messages is successfully delivered before sending the next
165  * batch, otherwise batches may arrive out of order as there is no guarantee
166  * the same channel or network path is used for each batch.
167  *
168  * For applications that do not care about message ordering, this can limit
169  * the throughput. Therefore, the behavior is disabled by default.
170  *
171  * @see the documentation for the `Publisher` class for details.
172  *
173  * @ingroup pubsub-options
174  */
176  using Type = bool;
177 };
178 
179 /// Actions taken by a full publisher.
181  /// Ignore full publishers, continue as usual.
182  kIgnored,
183  /// Configure the publisher to reject new messages when full.
184  kRejects,
185  /// Configure the publisher to block the caller when full.
186  kBlocks
187 };
188 /**
189  * The action taken by a full publisher.
190  *
191  * @ingroup pubsub-options
192  */
194  using Type = FullPublisherAction;
195 };
196 
197 /**
198  * Compression threshold.
199  *
200  * If set, the client library turns on gRPC compression for batches larger (in
201  * bytes) than the give threshold.
202  *
203  * @ingroup pubsub-options
204  */
206  using Type = std::size_t;
207 };
208 
209 /**
210  * Compression algorithm.
211  *
212  * Select the gRPC compression algorithm when compression is enabled. As of this
213  * writing, gRPC supports `GRPC_COMPRESS_DEFLATE` and `GRPC_COMPRESS_GZIP`.
214  * Other values may be added in the future and should be settable via this
215  * feature.
216  *
217  * @ingroup pubsub-options
218  */
220  using Type = int;
221 };
222 
223 /// The list of options specific to publishers.
224 using PublisherOptionList =
229 
230 /**
231  * The maximum deadline for each incoming message.
232  *
233  * Configure how long the application has to respond (ACK or NACK) to an
234  * incoming message. Note that this might be longer, or shorter, than the
235  * deadline configured in the server-side subscription.
236  *
237  * The value `0` is reserved to leave the deadline unmodified and just use the
238  * server-side configuration.
239  *
240  * @note The deadline applies to each message as it is delivered to the
241  * application, thus, if the library receives a batch of N messages their
242  * deadline for all the messages is extended repeatedly. Only once the
243  * message is delivered to a callback does the deadline become immutable.
244  *
245  * @ingroup pubsub-options
246  */
248  using Type = std::chrono::seconds;
249 };
250 
251 /**
252  * The maximum time by which the deadline for each incoming message is extended.
253  *
254  * While waiting for an ack or nack, The Cloud Pub/Sub C++ client library will
255  * extend the deadline by at most this amount. The default extension time is 10
256  * minutes. An application may wish to reduce this extension time so the Pub/Sub
257  * service will resend a message sooner when it does not hear back from a
258  * Subscriber. With at-least-once semantics, making the time too short may
259  * increase the number of duplicate messages delivered by the service.
260  *
261  * The value is clamped between 10 seconds and 10 minutes. Note that this option
262  * also affects the effective range for `MinDeadlineExtensionOption`.
263  *
264  * @ingroup pubsub-options
265  */
267  using Type = std::chrono::seconds;
268 };
269 
270 /**
271  * The minimum time by which the deadline for each incoming message is extended.
272  *
273  * While waiting for an ack or nack from the application the Cloud Pub/Sub C++
274  * client library will extend the deadline by at least this amount. The default
275  * minimum extension is 1 minute. An application may wish to reduce this
276  * extension so that the Pub/Sub service will resend a message sooner when it
277  * does not hear back from a Subscriber. An application may wish to increase
278  * this extension time to avoid duplicate message delivery.
279  *
280  * The value is clamped between 10 seconds and 10 minutes. Furthermore, if the
281  * application configures `MaxDeadlineExtensionOption`, then
282  * `MinDeadlineExtensionOption` is clamped between 10 seconds and the value of
283  * `MaxDeadlineExtensionOption`.
284  *
285  * @ingroup pubsub-options
286  */
288  using Type = std::chrono::seconds;
289 };
290 
291 /**
292  * The maximum number of outstanding messages per streaming pull.
293  *
294  * The Cloud Pub/Sub C++ client library uses streaming pull requests to receive
295  * messages from the service. The service will stop delivering messages if this
296  * many messages or more have neither been acknowledged nor rejected.
297  *
298  * If a negative or 0 value is supplied, the number of messages will be
299  * unlimited.
300  *
301  * @par Example
302  * @snippet samples.cc subscriber-flow-control
303  *
304  * @ingroup pubsub-options
305  */
307  using Type = std::int64_t;
308 };
309 
310 /**
311  * The maximum number of outstanding bytes per streaming pull.
312  *
313  * The Cloud Pub/Sub C++ client library uses streaming pull requests to receive
314  * messages from the service. The service will stop delivering messages if this
315  * many bytes or more worth of messages have not been acknowledged nor rejected.
316  *
317  * If a negative or 0 value is supplied, the number of bytes will be unlimited.
318  *
319  * @par Example
320  * @snippet samples.cc subscriber-flow-control
321  *
322  * @ingroup pubsub-options
323  */
325  using Type = std::int64_t;
326 };
327 
328 /**
329  * The maximum callback concurrency.
330  *
331  * The Cloud Pub/Sub C++ client library will schedule parallel callbacks as long
332  * as the number of outstanding callbacks is less than this maximum.
333  *
334  * Note that this controls the number of callbacks *scheduled*, not the number
335  * of callbacks actually executing at a time. The application needs to create
336  * (or configure) the background threads pool with enough parallelism to execute
337  * more than one callback at a time.
338  *
339  * Some applications may want to share a thread pool across many subscriptions.
340  * The additional level of control (scheduled vs. running callbacks) allows
341  * applications, for example, to ensure that at most `K` threads in the pool are
342  * used by any given subscription.
343  *
344  * @par Example
345  * @snippet samples.cc subscriber-concurrency
346  *
347  * @ingroup pubsub-options
348  */
350  using Type = std::size_t;
351 };
352 
353 /**
354  * How often the session polls for automatic shutdowns.
355  *
356  * Applications can shutdown a session by calling `.cancel()` on the returned
357  * `future<Status>`. In addition, applications can fire & forget a session,
358  * which is only shutdown once the completion queue servicing the session shuts
359  * down. In this latter case the session polls periodically to detect if the CQ
360  * has shutdown. This controls how often this polling happens.
361  *
362  * @ingroup pubsub-options
363  */
365  using Type = std::chrono::milliseconds;
366 };
367 
368 /**
369  * Override the default subscription for a request.
370  *
371  * Some applications need to receive messages from multiple subscriptions. In
372  * this case they can use this option to override the default subscription
373  * in a `Subscriber::Pull()` or `Subscriber::Subscribe()` call.
374  *
375  * @ingroup pubsub-options
376  */
378  using Type = Subscription;
379 };
380 
381 /// The list of options specific to subscribers.
382 /// @ingroup pubsub-options
383 using SubscriberOptionList =
388 
389 /**
390  * Convenience function to initialize a
391  * `google::cloud::iam::IAMPolicyConnection`.
392  *
393  * To manage the IAM policies of Pub/Sub resources you need to configure the
394  * `google::cloud::IAMPolicyClient` to use `pubsub.googleapis.com` as the
395  * `google::cloud::EndpointOption` and `google::cloud::AuthorityOption`.
396  *
397  * This function returns an object that is initialized with these values, you
398  * can provide additional configuration, or override some of the values before
399  * passing the object to `google::cloud::iam::MakeIAMPolicyConnection`.
400  *
401  * @ingroup pubsub-options
402  */
404 
406 } // namespace pubsub
407 } // namespace cloud
408 } // namespace google
409 
410 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_OPTIONS_H