Google Cloud Pub/Sub C++ Client  1.34.1
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 // http://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/version.h"
44 #include "google/cloud/options.h"
45 #include <chrono>
46 
47 namespace google {
48 namespace cloud {
49 namespace pubsub {
51 
52 /// The retry policy
54  using Type = std::shared_ptr<pubsub::RetryPolicy>;
55 };
56 
57 /// The backoff policy
59  using Type = std::shared_ptr<pubsub::BackoffPolicy>;
60 };
61 
62 /// The list of all "policy" options.
63 using PolicyOptionList = OptionList<RetryPolicyOption, BackoffPolicyOption>;
64 
65 /**
66  * The maximum hold time for the messages.
67  *
68  * @note The implementation depends on the granularity of your OS timers. It is
69  * possible that messages are held for slightly longer times than the value
70  * set here.
71  *
72  * @note The first message in a batch starts the hold time counter. New
73  * messages do not extend the life of the batch. For example, if you have
74  * set the holding time to 10 milliseconds, start a batch with message 1,
75  * and publish a second message 5 milliseconds later, the second message
76  * will be flushed approximately 5 milliseconds after it is published.
77  */
79  using Type = std::chrono::microseconds;
80 };
81 
82 /**
83  * The maximum number of messages in a batch.
84  *
85  * @note Application developers should keep in mind that Cloud Pub/Sub
86  * sets [limits][pubsub-quota-link] on the size of a batch (1,000 messages)
87  * The library makes no attempt to validate the value provided in this
88  * option.
89  *
90  * [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
91  */
93  using Type = std::size_t;
94 };
95 
96 /**
97  * The maximum size for the messages in a batch.
98  *
99  * @note Application developers should keep in mind that Cloud Pub/Sub
100  * sets [limits][pubsub-quota-link] on the size of a batch (10MB). The
101  * library makes no attempt to validate the value provided in this
102  * option.
103  *
104  * [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
105  */
107  using Type = std::size_t;
108 };
109 
110 /**
111  * The maximum number of pending messages.
112  *
113  * After a publisher flushes a batch of messages the batch is (obviously) not
114  * received immediately by the service. While the batch remains pending it
115  * potentially consumes memory resources in the client (and/or the service).
116  *
117  * Some applications may have constraints on the number of bytes and/or
118  * messages they can tolerate in this pending state, and may prefer to block
119  * or reject messages.
120  */
122  using Type = std::size_t;
123 };
124 
125 /**
126  * The maximum size for 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  */
137  using Type = std::size_t;
138 };
139 
140 /**
141  * Publisher message ordering.
142  *
143  * To guarantee messages are received by the service in the same order that
144  * the application gives them to a publisher, the client library needs to wait
145  * until a batch of messages is successfully delivered before sending the next
146  * batch, otherwise batches may arrive out of order as there is no guarantee
147  * the same channel or network path is used for each batch.
148  *
149  * For applications that do not care about message ordering, this can limit
150  * the throughput. Therefore, the behavior is disabled by default.
151  *
152  * @see the documentation for the `Publisher` class for details.
153  */
155  using Type = bool;
156 };
157 
158 /// Actions taken by a full publisher.
160  /// Ignore full publishers, continue as usual.
161  kIgnored,
162  /// Configure the publisher to reject new messages when full.
163  kRejects,
164  /// Configure the publisher to block the caller when full.
165  kBlocks
166 };
167 /// The action taken by a full publisher.
169  using Type = FullPublisherAction;
170 };
171 
172 /// The list of options specific to publishers.
173 using PublisherOptionList =
177 
178 /**
179  * The maximum deadline for each incoming message.
180  *
181  * Configure how long the application has to respond (ACK or NACK) to an
182  * incoming message. Note that this might be longer, or shorter, than the
183  * deadline configured in the server-side subscription.
184  *
185  * The value `0` is reserved to leave the deadline unmodified and just use the
186  * server-side configuration.
187  *
188  * @note The deadline applies to each message as it is delivered to the
189  * application, thus, if the library receives a batch of N messages their
190  * deadline for all the messages is extended repeatedly. Only once the
191  * message is delivered to a callback does the deadline become immutable.
192  */
194  using Type = std::chrono::seconds;
195 };
196 
197 /**
198  * The maximum time by which the deadline for each incoming message is extended.
199  *
200  * The Cloud Pub/Sub C++ client library will extend the deadline by at most this
201  * amount, while waiting for an ack or nack. The default extension is 10
202  * minutes. An application may wish to reduce this extension so that the Pub/Sub
203  * service will resend a message sooner when it does not hear back from a
204  * Subscriber.
205  *
206  * The value is clamped between 10 seconds and 10 minutes.
207  */
209  using Type = std::chrono::seconds;
210 };
211 
212 /**
213  * The maximum number of outstanding messages per streaming pull.
214  *
215  * The Cloud Pub/Sub C++ client library uses streaming pull requests to receive
216  * messages from the service. The service will stop delivering messages if this
217  * many messages or more have neither been acknowledged nor rejected.
218  *
219  * If a negative or 0 value is supplied, the number of messages will be
220  * unlimited.
221  *
222  * @par Example
223  * @snippet samples.cc subscriber-flow-control
224  */
226  using Type = std::int64_t;
227 };
228 
229 /**
230  * The maximum number of outstanding bytes per streaming pull.
231  *
232  * The Cloud Pub/Sub C++ client library uses streaming pull requests to receive
233  * messages from the service. The service will stop delivering messages if this
234  * many bytes or more worth of messages have not been acknowledged nor rejected.
235  *
236  * If a negative or 0 value is supplied, the number of bytes will be unlimited.
237  *
238  * @par Example
239  * @snippet samples.cc subscriber-flow-control
240  */
242  using Type = std::int64_t;
243 };
244 
245 /**
246  * The maximum callback concurrency.
247  *
248  * The Cloud Pub/Sub C++ client library will schedule parallel callbacks as long
249  * as the number of outstanding callbacks is less than this maximum.
250  *
251  * Note that this controls the number of callbacks *scheduled*, not the number
252  * of callbacks actually executing at a time. The application needs to create
253  * (or configure) the background threads pool with enough parallelism to execute
254  * more than one callback at a time.
255  *
256  * Some applications may want to share a thread pool across many subscriptions.
257  * The additional level of control (scheduled vs. running callbacks) allows
258  * applications, for example, to ensure that at most `K` threads in the pool are
259  * used by any given subscription.
260  *
261  * @par Example
262  * @snippet samples.cc subscriber-concurrency
263  */
265  using Type = std::size_t;
266 };
267 
268 /**
269  * How often the session polls for automatic shutdowns.
270  *
271  * Applications can shutdown a session by calling `.cancel()` on the returned
272  * `future<Status>`. In addition, applications can fire & forget a session,
273  * which is only shutdown once the completion queue servicing the session shuts
274  * down. In this latter case the session polls periodically to detect if the CQ
275  * has shutdown. This controls how often this polling happens.
276  */
278  using Type = std::chrono::milliseconds;
279 };
280 
281 /// The list of options specific to subscribers.
282 using SubscriberOptionList =
286 
288 } // namespace pubsub
289 } // namespace cloud
290 } // namespace google
291 
292 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_OPTIONS_H