Google Cloud Pub/Sub C++ Client  1.33.0
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 // 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_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  * @par Example
57  * @snippet samples.cc publisher-options
58  *
59  * [pubsub-pricing-link]: https://cloud.google.com/pubsub/pricing
60  */
62  public:
64 
65  /**
66  * Initialize the publisher options.
67  *
68  * Expected options are any of the types in the `PublisherOptionList`
69  *
70  * @note Unrecognized options will be ignored. To debug issues with options
71  * set `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment and
72  * unexpected options will be logged.
73  *
74  * @param opts configuration options
75  */
76  explicit PublisherOptions(Options opts);
77 
78  //@{
79  /**
80  * @name Publisher batch control
81  *
82  * It is more efficient (in terms of client CPU and client network usage) to
83  * send multiple messages in a single "batch" to the service. The following
84  * configuration options can be used to improve throughput: sending larger
85  * batches reduces CPU and network overhead. Note that batches are subject
86  * to [quota limits].
87  *
88  * [quota limits]: https://cloud.google.com/pubsub/quotas#resource_limits
89  */
90  std::chrono::microseconds maximum_hold_time() const {
91  return opts_.get<MaxHoldTimeOption>();
92  }
93 
94  /**
95  * Sets the maximum hold time for the messages.
96  *
97  * @note While this function accepts durations in arbitrary precision, the
98  * implementation depends on the granularity of your OS timers. It is
99  * possible that messages are held for slightly longer times than the
100  * value set here.
101  *
102  * @note The first message in a batch starts the hold time counter. New
103  * messages do not extend the life of the batch. For example, if you have
104  * set the holding time to 10 milliseconds, start a batch with message 1,
105  * and publish a second message 5 milliseconds later, the second message
106  * will be flushed approximately 5 milliseconds after it is published.
107  */
108  template <typename Rep, typename Period>
110  std::chrono::duration<Rep, Period> v) {
111  opts_.set<MaxHoldTimeOption>(
112  std::chrono::duration_cast<std::chrono::microseconds>(v));
113  return *this;
114  }
115 
116  std::size_t maximum_batch_message_count() const {
117  return opts_.get<MaxBatchMessagesOption>();
118  }
119 
120  /**
121  * Set the maximum number of messages in a batch.
122  *
123  * @note Application developers should keep in mind that Cloud Pub/Sub
124  * sets [limits][pubsub-quota-link] on the size of a batch (1,000 messages)
125  * The library makes no attempt to validate the value provided in this
126  * function.
127  *
128  * [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
129  */
132  return *this;
133  }
134 
135  std::size_t maximum_batch_bytes() const {
136  return opts_.get<MaxBatchBytesOption>();
137  }
138 
139  /**
140  * Set the maximum size for the messages in a batch.
141  *
142  * @note Application developers should keep in mind that Cloud Pub/Sub
143  * sets [limits][pubsub-quota-link] on the size of a batch (10MB). The
144  * library makes no attempt to validate the value provided in this
145  * function.
146  *
147  * [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
148  */
151  return *this;
152  }
153  //@}
154 
155  //@{
156  /**
157  * @name Publisher message ordering.
158  *
159  * To guarantee messages are received by the service in the same order that
160  * the application gives them to a publisher, the client library needs to wait
161  * until a batch of messages is successfully delivered before sending the next
162  * batch, otherwise batches may arrive out of order as there is no guarantee
163  * the same channel or network path is used for each batch.
164  *
165  * For applications that do not care about message ordering, this can limit
166  * the throughput. Therefore, the behavior is disabled by default.
167  */
168 
169  /// Return `true` if message ordering is enabled.
170  bool message_ordering() const { return opts_.get<MessageOrderingOption>(); }
171 
172  /**
173  * Enable message ordering.
174  *
175  * @see the documentation for the `Publisher` class for details.
176  */
179  return *this;
180  }
181 
182  /**
183  * Disable message ordering.
184  *
185  * @see the documentation for the `Publisher` class for details.
186  */
189  return *this;
190  }
191  //@}
192 
193  //@{
194  /**
195  * @name Publisher flow control.
196  *
197  * After a publisher flushes a batch of messages the batch is (obviously) not
198  * received immediately by the service. While the batch remains pending it
199  * potentially consumes memory resources in the client (and/or the service).
200  *
201  * Some applications may have constraints on the number of bytes and/or
202  * messages they can tolerate in this pending state, and may prefer to block
203  * or reject messages.
204  */
205 
206  /// Flow control based on pending bytes.
209  return *this;
210  }
211 
212  /// Flow control based on pending messages.
215  return *this;
216  }
217 
218  std::size_t maximum_pending_bytes() const {
219  return opts_.get<MaxPendingBytesOption>();
220  }
221  std::size_t maximum_pending_messages() const {
223  }
224 
225  /// The current action for a full publisher
226  bool full_publisher_ignored() const {
227  return opts_.get<FullPublisherActionOption>() ==
229  }
230  bool full_publisher_rejects() const {
231  return opts_.get<FullPublisherActionOption>() ==
233  }
234  bool full_publisher_blocks() const {
235  return opts_.get<FullPublisherActionOption>() ==
237  }
238 
239  /// Ignore full publishers, continue as usual
242  return *this;
243  }
244 
245  /// Configure the publisher to reject new messages when full.
248  return *this;
249  }
250 
251  /// Configure the publisher to block the caller when full.
254  return *this;
255  }
256  //@}
257 
258  private:
259  friend Options pubsub_internal::MakeOptions(PublisherOptions);
260  Options opts_;
261 };
262 
264 } // namespace pubsub
265 
266 namespace pubsub_internal {
268 
269 inline Options MakeOptions(pubsub::PublisherOptions o) {
270  return std::move(o.opts_);
271 }
272 
274 } // namespace pubsub_internal
275 } // namespace cloud
276 } // namespace google
277 
278 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_PUBLISHER_OPTIONS_H