Skip to content

Commit 22ecaf5

Browse files
coryancoryan
authored
doc(pubsub): create page for configuration options (#10198)
1 parent 733cea0 commit 22ecaf5

2 files changed

Lines changed: 56 additions & 3 deletions

File tree

‎google/cloud/pubsub/doc/pubsub-options.dox‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/*!
2+
@defgroup pubsub-options Pub/Sub Client Library Configuration Options
3+
4+
The Pub/Sub client library uses the same mechanism as all other C++ client
5+
libraries for configuration. As usual for the C++ client libraries, it adds a
6+
number of unique options only applicable for the Pub/Sub library.
7+
8+
@see @ref options - for an overview of client library configuration.
9+
*/

‎google/cloud/pubsub/options.h‎

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,12 +49,20 @@ namespace cloud {
4949
namespace pubsub {
5050
GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
5151

52-
/// The retry policy
52+
/**
53+
* The retry policy
54+
*
55+
* @ingroup pubsub-options
56+
*/
5357
struct RetryPolicyOption {
5458
using Type = std::shared_ptr<pubsub::RetryPolicy>;
5559
};
5660

57-
/// The backoff policy
61+
/**
62+
* The backoff policy
63+
*
64+
* @ingroup pubsub-options
65+
*/
5866
struct BackoffPolicyOption {
5967
using Type = std::shared_ptr<pubsub::BackoffPolicy>;
6068
};
@@ -74,6 +82,8 @@ using PolicyOptionList = OptionList<RetryPolicyOption, BackoffPolicyOption>;
7482
* set the holding time to 10 milliseconds, start a batch with message 1,
7583
* and publish a second message 5 milliseconds later, the second message
7684
* will be flushed approximately 5 milliseconds after it is published.
85+
*
86+
* @ingroup pubsub-options
7787
*/
7888
struct MaxHoldTimeOption {
7989
using Type = std::chrono::microseconds;
@@ -88,6 +98,8 @@ struct MaxHoldTimeOption {
8898
* option.
8999
*
90100
* [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
101+
*
102+
* @ingroup pubsub-options
91103
*/
92104
struct MaxBatchMessagesOption {
93105
using Type = std::size_t;
@@ -102,6 +114,8 @@ struct MaxBatchMessagesOption {
102114
* option.
103115
*
104116
* [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
117+
*
118+
* @ingroup pubsub-options
105119
*/
106120
struct MaxBatchBytesOption {
107121
using Type = std::size_t;
@@ -117,6 +131,8 @@ struct MaxBatchBytesOption {
117131
* Some applications may have constraints on the number of bytes and/or
118132
* messages they can tolerate in this pending state, and may prefer to block
119133
* or reject messages.
134+
*
135+
* @ingroup pubsub-options
120136
*/
121137
struct MaxPendingMessagesOption {
122138
using Type = std::size_t;
@@ -132,6 +148,8 @@ struct MaxPendingMessagesOption {
132148
* Some applications may have constraints on the number of bytes and/or
133149
* messages they can tolerate in this pending state, and may prefer to block
134150
* or reject messages.
151+
*
152+
* @ingroup pubsub-options
135153
*/
136154
struct MaxPendingBytesOption {
137155
using Type = std::size_t;
@@ -150,6 +168,8 @@ struct MaxPendingBytesOption {
150168
* the throughput. Therefore, the behavior is disabled by default.
151169
*
152170
* @see the documentation for the `Publisher` class for details.
171+
*
172+
* @ingroup pubsub-options
153173
*/
154174
struct MessageOrderingOption {
155175
using Type = bool;
@@ -164,7 +184,11 @@ enum class FullPublisherAction {
164184
/// Configure the publisher to block the caller when full.
165185
kBlocks
166186
};
167-
/// The action taken by a full publisher.
187+
/**
188+
* The action taken by a full publisher.
189+
*
190+
* @ingroup pubsub-options
191+
*/
168192
struct FullPublisherActionOption {
169193
using Type = FullPublisherAction;
170194
};
@@ -174,6 +198,8 @@ struct FullPublisherActionOption {
174198
*
175199
* If set, the client library turns on gRPC compression for batches larger (in
176200
* bytes) than the give threshold.
201+
*
202+
* @ingroup pubsub-options
177203
*/
178204
struct CompressionThresholdOption {
179205
using Type = std::size_t;
@@ -186,6 +212,8 @@ struct CompressionThresholdOption {
186212
* writing, gRPC supports `GRPC_COMPRESS_DEFLATE` and `GRPC_COMPRESS_GZIP`.
187213
* Other values may be added in the future and should be settable via this
188214
* feature.
215+
*
216+
* @ingroup pubsub-options
189217
*/
190218
struct CompressionAlgorithmOption {
191219
using Type = int;
@@ -212,6 +240,8 @@ using PublisherOptionList =
212240
* application, thus, if the library receives a batch of N messages their
213241
* deadline for all the messages is extended repeatedly. Only once the
214242
* message is delivered to a callback does the deadline become immutable.
243+
*
244+
* @ingroup pubsub-options
215245
*/
216246
struct MaxDeadlineTimeOption {
217247
using Type = std::chrono::seconds;
@@ -229,6 +259,8 @@ struct MaxDeadlineTimeOption {
229259
*
230260
* The value is clamped between 10 seconds and 10 minutes. Note that this option
231261
* also affects the effective range for `MinDeadlineExtensionOption`.
262+
*
263+
* @ingroup pubsub-options
232264
*/
233265
struct MaxDeadlineExtensionOption {
234266
using Type = std::chrono::seconds;
@@ -248,6 +280,8 @@ struct MaxDeadlineExtensionOption {
248280
* application configures `MaxDeadlineExtensionOption`, then
249281
* `MinDeadlineExtensionOption` is clamped between 10 seconds and the value of
250282
* `MaxDeadlineExtensionOption`.
283+
*
284+
* @ingroup pubsub-options
251285
*/
252286
struct MinDeadlineExtensionOption {
253287
using Type = std::chrono::seconds;
@@ -265,6 +299,8 @@ struct MinDeadlineExtensionOption {
265299
*
266300
* @par Example
267301
* @snippet samples.cc subscriber-flow-control
302+
*
303+
* @ingroup pubsub-options
268304
*/
269305
struct MaxOutstandingMessagesOption {
270306
using Type = std::int64_t;
@@ -281,6 +317,8 @@ struct MaxOutstandingMessagesOption {
281317
*
282318
* @par Example
283319
* @snippet samples.cc subscriber-flow-control
320+
*
321+
* @ingroup pubsub-options
284322
*/
285323
struct MaxOutstandingBytesOption {
286324
using Type = std::int64_t;
@@ -304,6 +342,8 @@ struct MaxOutstandingBytesOption {
304342
*
305343
* @par Example
306344
* @snippet samples.cc subscriber-concurrency
345+
*
346+
* @ingroup pubsub-options
307347
*/
308348
struct MaxConcurrencyOption {
309349
using Type = std::size_t;
@@ -317,6 +357,8 @@ struct MaxConcurrencyOption {
317357
* which is only shutdown once the completion queue servicing the session shuts
318358
* down. In this latter case the session polls periodically to detect if the CQ
319359
* has shutdown. This controls how often this polling happens.
360+
*
361+
* @ingroup pubsub-options
320362
*/
321363
struct ShutdownPollingPeriodOption {
322364
using Type = std::chrono::milliseconds;
@@ -340,6 +382,8 @@ using SubscriberOptionList =
340382
* This function returns an object that is initialized with these values, you
341383
* can provide additional configuration, or override some of the values before
342384
* passing the object to `google::cloud::iam::MakeIAMPolicyConnection`.
385+
*
386+
* @ingroup pubsub-options
343387
*/
344388
Options IAMPolicyOptions(Options opts = {});
345389

0 commit comments

Comments
 (0)