Google Cloud Pub/Sub C++ Client  2.5.0
A C++ Client Library for Google Cloud Pub/Sub
subscriber_options.h
Go to the documentation of this file.
1 // Copyright 2020 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_SUBSCRIBER_OPTIONS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SUBSCRIBER_OPTIONS_H
17 
18 #include "google/cloud/pubsub/options.h"
19 #include "google/cloud/pubsub/version.h"
20 #include "google/cloud/options.h"
21 #include <chrono>
22 #include <thread>
23 
24 namespace google {
25 namespace cloud {
26 namespace pubsub {
28 class SubscriberOptions;
30 } // namespace pubsub
31 
32 namespace pubsub_internal {
34 Options MakeOptions(pubsub::SubscriberOptions);
36 } // namespace pubsub_internal
37 
38 namespace pubsub {
40 
41 /**
42  * Configure how a `Subscriber` handles incoming messages.
43  *
44  * There are two main algorithms controlled by this function: the dispatching of
45  * application callbacks, and requesting more data from the service.
46  *
47  * @par Callback Concurrency Control
48  * @parblock
49  * The subscription configuration determines the upper limit (set
50  * `set_concurrency_watermarks()`) how many callbacks are *scheduled* at a time.
51  * As long as this limit is not reached the library will continue to schedule
52  * callbacks, once the limit is reached the library will wait until the number
53  * of executing callbacks goes below the low watermark.
54  *
55  * A callback is "executing" until the `AckHandler::ack()` or
56  * `AckHandler::nack()` function is called on the associated `AckHandler`.
57  * Applications can use this to move long-running computations out of the
58  * library internal thread pool.
59  *
60  * Note that callbacks are "scheduled", but they may not immediately execute.
61  * For example, callbacks may be sequenced if the concurrency control parameters
62  * are higher than the number of I/O threads configured in the
63  * `SubscriberConnection`.
64  *
65  * The default value for the concurrency high watermarks is set to the value
66  * returned by `std::thread::hardware_concurrency()` (or 4 if your standard
67  * library returns `0` for this parameter).
68  * @endparblock
69  *
70  * @par Message Flow Control
71  * @parblock
72  * The subscription will request more messages from the service as long as
73  * both the outstanding message count (see `set_message_count_watermarks()`)
74  * and the number of bytes in the outstanding messages (see
75  * `set_message_size_watermarks()`) are below the high watermarks for these
76  * values.
77  *
78  * Once either of the high watermarks are breached the library will wait until
79  * **both** the values are below their low watermarks before requesting more
80  * messages from the service.
81  *
82  * In this algorithm a message is outstanding until the `AckHandler::ack()` or
83  * `AckHandler::nack()` function is called on the associated `AckHandler`. Note
84  * that if the concurrency control algorithm has not scheduled a callback this
85  * can also put back pressure on the flow control algorithm.
86  * @endparblock
87  *
88  * @deprecated We recommend you use `google::cloud::Options` and pass any
89  * subscriber options to `MakeSubscriberConnection()`.
90  *
91  * @par Example: setting the concurrency control parameters
92  * @snippet samples.cc subscriber-concurrency
93  *
94  * @par Example: setting the flow control parameters
95  * @snippet samples.cc subscriber-flow-control
96  */
98  public:
99  /**
100  * Initialize the subscriber options with default values.
101  *
102  * @deprecated Use `google::cloud::Options` instead.
103  */
104  GOOGLE_CLOUD_CPP_DEPRECATED("Use `google::cloud::Options` instead")
106 
107  /**
108  * Initialize the subscriber options.
109  *
110  * Expected options are any of the types in the `SubscriberOptionList`
111  *
112  * @note Unrecognized options will be ignored. To debug issues with options
113  * set `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment and
114  * unexpected options will be logged.
115  *
116  * @param opts configuration options
117  *
118  * @deprecated Use `google::cloud::Options` instead.
119  */
120  GOOGLE_CLOUD_CPP_DEPRECATED("Use `google::cloud::Options` instead")
121  explicit SubscriberOptions(Options opts);
122 
123  /**
124  * The maximum deadline for each incoming message.
125  *
126  * Configure how long does the application have to respond (ACK or NACK) an
127  * incoming message. Note that this might be longer, or shorter, than the
128  * deadline configured in the server-side subscription.
129  *
130  * The value `0` is reserved to leave the deadline unmodified and just use the
131  * server-side configuration.
132  *
133  * @note The deadline applies to each message as it is delivered to the
134  * application, thus, if the library receives a batch of N messages their
135  * deadline for all the messages is extended repeatedly. Only once the
136  * message is delivered to a callback does the deadline become immutable.
137  *
138  * @deprecated Use `google::cloud::Options` and `MaxDeadlineTimeOption`
139  * instead.
140  */
141  GOOGLE_CLOUD_CPP_DEPRECATED(
142  "use `google::cloud::Options` and `MaxDeadlineTimeOption` instead")
143  std::chrono::seconds max_deadline_time() const {
144  return opts_.get<MaxDeadlineTimeOption>();
145  }
146 
147  /**
148  * Set the maximum deadline for incoming messages.
149  *
150  * @deprecated Use `google::cloud::Options` and `MaxDeadlineTimeOption`
151  * instead.
152  */
153  GOOGLE_CLOUD_CPP_DEPRECATED(
154  "use `google::cloud::Options` and `MaxDeadlineTimeOption` instead")
155  SubscriberOptions& set_max_deadline_time(std::chrono::seconds d) {
157  return *this;
158  }
159 
160  /**
161  * Set the maximum time by which the deadline for each incoming message is
162  * extended.
163  *
164  * The Cloud Pub/Sub C++ client library will extend the deadline by at most
165  * this amount, while waiting for an ack or nack. The default extension is 10
166  * minutes. An application may wish to reduce this extension so that the
167  * Pub/Sub service will resend a message sooner when it does not hear back
168  * from a Subscriber.
169  *
170  * The value is clamped between 10 seconds and 10 minutes.
171  *
172  * @param extension the maximum time that the deadline can be extended by,
173  * measured in seconds.
174  *
175  * @deprecated Use `google::cloud::Options` and `MaxDeadlineExtensionOption`
176  * instead.
177  */
178  GOOGLE_CLOUD_CPP_DEPRECATED(
179  "use `google::cloud::Options` and `MaxDeadlineExtensionOption` instead")
180  SubscriberOptions& set_max_deadline_extension(std::chrono::seconds extension);
181 
182  /// @deprecated Use `google::cloud::Options` and `MaxDeadlineExtensionOption`
183  /// instead.
184  GOOGLE_CLOUD_CPP_DEPRECATED(
185  "use `google::cloud::Options` and `MaxDeadlineExtensionOption` instead")
186  std::chrono::seconds max_deadline_extension() const {
188  }
189 
190  /**
191  * Set the maximum number of outstanding messages per streaming pull.
192  *
193  * The Cloud Pub/Sub C++ client library uses streaming pull requests to
194  * receive messages from the service. The service will stop delivering
195  * messages if @p message_count or more messages have not been acknowledged
196  * nor rejected.
197  *
198  * @par Example
199  * @snippet samples.cc subscriber-flow-control
200  *
201  * @param message_count the maximum number of messages outstanding, use 0 or
202  * negative numbers to make the message count unlimited.
203  *
204  * @deprecated Use `google::cloud::Options` and `MaxOutstandingMessagesOption`
205  * instead.
206  */
207  GOOGLE_CLOUD_CPP_DEPRECATED(
208  "use `google::cloud::Options` and `MaxOutstandingMessagesOption` instead")
209  SubscriberOptions& set_max_outstanding_messages(std::int64_t message_count);
210 
211  /// @deprecated Use `google::cloud::Options` and
212  /// `MaxOutstandingMessagesOption` instead.
213  GOOGLE_CLOUD_CPP_DEPRECATED(
214  "use `google::cloud::Options` and `MaxOutstandingMessagesOption` instead")
215  std::int64_t max_outstanding_messages() const {
217  }
218 
219  /**
220  * Set the maximum number of outstanding bytes per streaming pull.
221  *
222  * The Cloud Pub/Sub C++ client library uses streaming pull requests to
223  * receive messages from the service. The service will stop delivering
224  * messages if @p bytes or more worth of messages have not been
225  * acknowledged nor rejected.
226  *
227  * @par Example
228  * @snippet samples.cc subscriber-flow-control
229  *
230  * @param bytes the maximum number of bytes outstanding, use 0 or negative
231  * numbers to make the number of bytes unlimited.
232  *
233  * @deprecated Use `google::cloud::Options` and `MaxOutstandingBytesOption`
234  * instead.
235  */
236  GOOGLE_CLOUD_CPP_DEPRECATED(
237  "use `google::cloud::Options` and `MaxOutstandingBytesOption` instead")
239 
240  /// @deprecated Use `google::cloud::Options` and `MaxOutstandingBytesOption`
241  /// instead.
242  GOOGLE_CLOUD_CPP_DEPRECATED(
243  "use `google::cloud::Options` and `MaxOutstandingBytesOption` instead")
244  std::int64_t max_outstanding_bytes() const {
246  }
247 
248  /**
249  * Set the maximum callback concurrency.
250  *
251  * The Cloud Pub/Sub C++ client library will schedule parallel callbacks as
252  * long as the number of outstanding callbacks is less than this maximum.
253  *
254  * Note that this controls the number of callbacks *scheduled*, not the number
255  * of callbacks actually executing at a time. The application needs to create
256  * (or configure) the background threads pool with enough parallelism to
257  * execute more than one callback at a time.
258  *
259  * Some applications may want to share a thread pool across many
260  * subscriptions, the additional level of control (scheduled vs. running
261  * callbacks) allows applications, for example, to ensure that at most `K`
262  * threads in the pool are used by any given subscription.
263  *
264  * @par Example
265  * @snippet samples.cc subscriber-concurrency
266  *
267  * @param v the new value, 0 resets to the default
268  *
269  * @deprecated Use `google::cloud::Options` and `MaxConcurrencyOption`
270  * instead.
271  */
272  GOOGLE_CLOUD_CPP_DEPRECATED(
273  "use `google::cloud::Options` and `MaxConcurrencyOption` instead")
275 
276  /**
277  * Maximum number of callbacks scheduled by the library at a time.
278  *
279  * @deprecated Use `google::cloud::Options` and `MaxConcurrencyOption`
280  * instead.
281  */
282  GOOGLE_CLOUD_CPP_DEPRECATED(
283  "use `google::cloud::Options` and `MaxConcurrencyOption` instead")
284  std::size_t max_concurrency() const {
285  return opts_.get<MaxConcurrencyOption>();
286  }
287 
288  /**
289  * Control how often the session polls for automatic shutdowns.
290  *
291  * Applications can shutdown a session by calling `.cancel()` on the returned
292  * `future<Status>`. In addition, applications can fire & forget a session,
293  * which is only shutdown once the completion queue servicing the session
294  * shuts down. In this latter case the session polls periodically to detect
295  * if the CQ has shutdown. This controls how often this polling happens.
296  *
297  * @deprecated Use `google::cloud::Options` and `ShutdownPollingPeriodOption`
298  * instead.
299  */
300  GOOGLE_CLOUD_CPP_DEPRECATED(
301  "use `google::cloud::Options` and `ShutdownPollingPeriodOption` instead")
302  SubscriberOptions& set_shutdown_polling_period(std::chrono::milliseconds v) {
304  return *this;
305  }
306 
307  /// @deprecated Use `google::cloud::Options` and `ShutdownPollingPeriodOption`
308  /// instead.
309  GOOGLE_CLOUD_CPP_DEPRECATED(
310  "use `google::cloud::Options` and `ShutdownPollingPeriodOption` instead")
311  std::chrono::milliseconds shutdown_polling_period() const {
313  }
314 
315  private:
316  friend Options pubsub_internal::MakeOptions(SubscriberOptions);
317  Options opts_;
318 };
319 
321 } // namespace pubsub
322 
323 namespace pubsub_internal {
325 
326 inline Options MakeOptions(pubsub::SubscriberOptions o) {
327  return std::move(o.opts_);
328 }
329 
331 } // namespace pubsub_internal
332 } // namespace cloud
333 } // namespace google
334 
335 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SUBSCRIBER_OPTIONS_H