Google Cloud Pub/Sub C++ Client  2.2.1
A C++ Client Library for Google Cloud Pub/Sub
publisher_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_PUBLISHER_OPTIONS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_PUBLISHER_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 <algorithm>
22 #include <chrono>
23 #include <cstddef>
24 #include <limits>
25 
26 namespace google {
27 namespace cloud {
28 namespace pubsub {
30 class PublisherOptions;
32 } // namespace pubsub
33 
34 namespace pubsub_internal {
36 Options MakeOptions(pubsub::PublisherOptions);
38 } // namespace pubsub_internal
39 
40 namespace pubsub {
42 
43 /**
44  * Configuration options for a `Publisher`.
45  *
46  * These are largely used to control the batching configuration for a publisher.
47  * By default a publishers flushes a batch as soon as any of these conditions
48  * are met:
49  * - 10ms after the first message is put in the batch,
50  * - when the batch contains 100 messages or more,
51  * - when the batch contains 1MiB of data or more.
52  *
53  * Applications developers should consult the Cloud Pub/Sub
54  * [pricing page][pubsub-pricing-link] when selecting a batching configuration.
55  *
56  * @deprecated We recommend you use `google::cloud::Options` and pass the
57  * options to `MakePublisherConnection()`.
58  *
59  * @par Example
60  * @snippet samples.cc publisher-options
61  *
62  * [pubsub-pricing-link]: https://cloud.google.com/pubsub/pricing
63  */
65  public:
66  /// @deprecated Use `google::cloud::Options{}` instead.
67  GOOGLE_CLOUD_CPP_DEPRECATED("use `google::cloud::Options{}` instead")
69 
70  /**
71  * Initialize the publisher options.
72  *
73  * Expected options are any of the types in the `PublisherOptionList`
74  *
75  * @note Unrecognized options will be ignored. To debug issues with options
76  * set `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment and
77  * unexpected options will be logged.
78  *
79  * @param opts configuration options
80  *
81  * @deprecated Use `google::cloud::Options{}` instead.
82  */
83  GOOGLE_CLOUD_CPP_DEPRECATED("use `google::cloud::Options{}` instead")
84  explicit PublisherOptions(Options opts);
85 
86  /**
87  * @name Publisher batch control
88  *
89  * It is more efficient (in terms of client CPU and client network usage) to
90  * send multiple messages in a single "batch" to the service. The following
91  * configuration options can be used to improve throughput: sending larger
92  * batches reduces CPU and network overhead. Note that batches are subject
93  * to [quota limits].
94  *
95  * [quota limits]: https://cloud.google.com/pubsub/quotas#resource_limits
96  */
97  ///@{
98  /// @deprecated Use `google::cloud::Options{}` and `MaxHoldTimeOption`
99  /// instead.
100  GOOGLE_CLOUD_CPP_DEPRECATED(
101  "use `google::cloud::Options{}` and `MaxHoldTimeOption` instead")
102  std::chrono::microseconds maximum_hold_time() const {
103  return opts_.get<MaxHoldTimeOption>();
104  }
105 
106  /**
107  * Sets the maximum hold time for the messages.
108  *
109  * @note While this function accepts durations in arbitrary precision, the
110  * implementation depends on the granularity of your OS timers. It is
111  * possible that messages are held for slightly longer times than the
112  * value set here.
113  *
114  * @note The first message in a batch starts the hold time counter. New
115  * messages do not extend the life of the batch. For example, if you have
116  * set the holding time to 10 milliseconds, start a batch with message 1,
117  * and publish a second message 5 milliseconds later, the second message
118  * will be flushed approximately 5 milliseconds after it is published.
119  *
120  * @deprecated Use `google::cloud::Options{}` and `MaxHoldTimeOption` instead.
121  */
122  template <typename Rep, typename Period>
123  GOOGLE_CLOUD_CPP_DEPRECATED(
124  "use `google::cloud::Options{}` and `MaxHoldTimeOption` instead")
126  std::chrono::duration<Rep, Period> v) {
127  opts_.set<MaxHoldTimeOption>(
128  std::chrono::duration_cast<std::chrono::microseconds>(v));
129  return *this;
130  }
131 
132  /// @deprecated Use `google::cloud::Options{}` and `MaxBatchMessagesOption`
133  /// instead.
134  GOOGLE_CLOUD_CPP_DEPRECATED(
135  "use `google::cloud::Options{}` and `MaxBatchMessagesOption` instead")
136  std::size_t maximum_batch_message_count() const {
137  return opts_.get<MaxBatchMessagesOption>();
138  }
139 
140  /**
141  * Set the maximum number of messages in a batch.
142  *
143  * @note Application developers should keep in mind that Cloud Pub/Sub
144  * sets [limits][pubsub-quota-link] on the size of a batch (1,000 messages)
145  * The library makes no attempt to validate the value provided in this
146  * function.
147  *
148  * [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
149  *
150  * @deprecated Use `google::cloud::Options{}` and `MaxBatchMessagesOption`
151  * instead.
152  */
153  GOOGLE_CLOUD_CPP_DEPRECATED(
154  "use `google::cloud::Options{}` and `MaxBatchMessagesOption` instead")
157  return *this;
158  }
159 
160  /// @deprecated Use `google::cloud::Options{}` and `MaxBatchBytesOption`
161  /// instead.
162  GOOGLE_CLOUD_CPP_DEPRECATED(
163  "use `google::cloud::Options{}` and `MaxBatchBytesOption` instead")
164  std::size_t maximum_batch_bytes() const {
165  return opts_.get<MaxBatchBytesOption>();
166  }
167 
168  /**
169  * Set the maximum size for the messages in a batch.
170  *
171  * @note Application developers should keep in mind that Cloud Pub/Sub
172  * sets [limits][pubsub-quota-link] on the size of a batch (10MB). The
173  * library makes no attempt to validate the value provided in this
174  * function.
175  *
176  * [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
177  *
178  * @deprecated Use `google::cloud::Options{}` and `MaxBatchBytesOption`
179  * instead.
180  */
181  GOOGLE_CLOUD_CPP_DEPRECATED(
182  "use `google::cloud::Options{}` and `MaxBatchBytesOption` instead")
185  return *this;
186  }
187  ///@}
188 
189  /**
190  * @name Publisher message ordering.
191  *
192  * To guarantee messages are received by the service in the same order that
193  * the application gives them to a publisher, the client library needs to wait
194  * until a batch of messages is successfully delivered before sending the next
195  * batch, otherwise batches may arrive out of order as there is no guarantee
196  * the same channel or network path is used for each batch.
197  *
198  * For applications that do not care about message ordering, this can limit
199  * the throughput. Therefore, the behavior is disabled by default.
200  */
201  ///@{
202 
203  /**
204  * Return `true` if message ordering is enabled.
205  *
206  * @deprecated Use `google::cloud::Options{}` and `MessageOrderingOption`
207  * instead.
208  */
209  GOOGLE_CLOUD_CPP_DEPRECATED(
210  "use `google::cloud::Options{}` and `MessageOrderingOption` instead")
211  bool message_ordering() const { return opts_.get<MessageOrderingOption>(); }
212 
213  /**
214  * Enable message ordering.
215  *
216  * @deprecated Use `google::cloud::Options{}` and `MessageOrderingOption`
217  * instead.
218  *
219  * @see the documentation for the `Publisher` class for details.
220  */
221  GOOGLE_CLOUD_CPP_DEPRECATED(
222  "use `google::cloud::Options{}` and `MessageOrderingOption` instead")
225  return *this;
226  }
227 
228  /**
229  * Disable message ordering.
230  *
231  * @deprecated Use `google::cloud::Options{}` and `MessageOrderingOption`
232  * instead.
233  *
234  * @see the documentation for the `Publisher` class for details.
235  */
236  GOOGLE_CLOUD_CPP_DEPRECATED(
237  "use `google::cloud::Options{}` and `MessageOrderingOption` instead")
240  return *this;
241  }
242  ///@}
243 
244  /**
245  * @name Publisher flow control.
246  *
247  * After a publisher flushes a batch of messages the batch is (obviously) not
248  * received immediately by the service. While the batch remains pending it
249  * potentially consumes memory resources in the client (and/or the service).
250  *
251  * Some applications may have constraints on the number of bytes and/or
252  * messages they can tolerate in this pending state, and may prefer to block
253  * or reject messages.
254  */
255  ///@{
256 
257  /**
258  * Flow control based on pending bytes.
259  *
260  * @deprecated Use `google::cloud::Options{}` and `MaxPendingBytesOption`
261  * instead.
262  */
263  GOOGLE_CLOUD_CPP_DEPRECATED(
264  "use `google::cloud::Options{}` and `MaxPendingBytesOption` instead")
267  return *this;
268  }
269 
270  /**
271  * Flow control based on pending messages.
272  *
273  * @deprecated Use `google::cloud::Options{}` and `MaxPendingMessagesOption`
274  * instead.
275  */
276  GOOGLE_CLOUD_CPP_DEPRECATED(
277  "use `google::cloud::Options{}` and `MaxPendingMessagesOption` instead")
280  return *this;
281  }
282 
283  /// @deprecated Use `google::cloud::Options{}` and `MaxPendingBytesOption`
284  /// instead.
285  GOOGLE_CLOUD_CPP_DEPRECATED(
286  "use `google::cloud::Options{}` and `MaxPendingBytesOption` instead")
287  std::size_t maximum_pending_bytes() const {
288  return opts_.get<MaxPendingBytesOption>();
289  }
290 
291  /// @deprecated Use `google::cloud::Options{}` and `MaxPendingMessagesOption`
292  /// instead.
293  GOOGLE_CLOUD_CPP_DEPRECATED(
294  "use `google::cloud::Options{}` and `MaxPendingMessagesOption` instead")
295  std::size_t maximum_pending_messages() const {
297  }
298 
299  /**
300  * The current action for a full publisher.
301  *
302  * @deprecated Use `google::cloud::Options{}` and `FullPublisherActionOption`
303  * instead.
304  */
305  GOOGLE_CLOUD_CPP_DEPRECATED(
306  "use `google::cloud::Options{}` and `FullPublisherActionOption` instead")
307  bool full_publisher_ignored() const {
308  return opts_.get<FullPublisherActionOption>() ==
310  }
311 
312  /**
313  * The current action for a full publisher.
314  *
315  * @deprecated Use `google::cloud::Options{}` and `FullPublisherActionOption`
316  * instead.
317  */
318  GOOGLE_CLOUD_CPP_DEPRECATED(
319  "use `google::cloud::Options{}` and `FullPublisherActionOption` instead")
320  bool full_publisher_rejects() const {
321  return opts_.get<FullPublisherActionOption>() ==
323  }
324 
325  /**
326  * The current action for a full publisher.
327  *
328  * @deprecated Use `google::cloud::Options{}` and `FullPublisherActionOption`
329  * instead.
330  */
331  GOOGLE_CLOUD_CPP_DEPRECATED(
332  "use `google::cloud::Options{}` and `FullPublisherActionOption` instead")
333  bool full_publisher_blocks() const {
334  return opts_.get<FullPublisherActionOption>() ==
336  }
337 
338  /**
339  * Ignore full publishers, continue as usual
340  *
341  * @deprecated Use `google::cloud::Options{}` and `FullPublisherActionOption`
342  * instead.
343  */
344  GOOGLE_CLOUD_CPP_DEPRECATED(
345  "use `google::cloud::Options{}` and `FullPublisherActionOption` instead")
348  return *this;
349  }
350 
351  /**
352  * Configure the publisher to reject new messages when full.
353  *
354  * @deprecated Use `google::cloud::Options{}` and `FullPublisherActionOption`
355  * instead.
356  */
357  GOOGLE_CLOUD_CPP_DEPRECATED(
358  "use `google::cloud::Options{}` and `FullPublisherActionOption` instead")
361  return *this;
362  }
363 
364  /**
365  * Configure the publisher to block the caller when full.
366  *
367  * @deprecated Use `google::cloud::Options{}` and `FullPublisherActionOption`
368  * instead.
369  */
370  GOOGLE_CLOUD_CPP_DEPRECATED(
371  "use `google::cloud::Options{}` and `FullPublisherActionOption` instead")
374  return *this;
375  }
376  ///@}
377 
378  private:
379  friend Options pubsub_internal::MakeOptions(PublisherOptions);
380  Options opts_;
381 };
382 
384 } // namespace pubsub
385 
386 namespace pubsub_internal {
388 
389 inline Options MakeOptions(pubsub::PublisherOptions o) {
390  return std::move(o.opts_);
391 }
392 
394 } // namespace pubsub_internal
395 } // namespace cloud
396 } // namespace google
397 
398 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_PUBLISHER_OPTIONS_H