Google Cloud Pub/Sub C++ Client  1.32.1
A C++ Client Library for Google Cloud Pub/Sub
Public Member Functions | List of all members
google::cloud::pubsub::v1::PublisherOptions Class Reference

Configuration options for a Publisher. More...

#include <google/cloud/pubsub/publisher_options.h>

Public Member Functions

 PublisherOptions ()
 
 PublisherOptions (Options opts)
 Initialize the publisher options. More...
 
Publisher batch control

It is more efficient (in terms of client CPU and client network usage) to send multiple messages in a single "batch" to the service.

The following configuration options can be used to improve throughput: sending larger batches reduces CPU and network overhead. Note that batches are subject to quota limits.

std::chrono::microseconds maximum_hold_time () const
 Sets the maximum hold time for the messages. More...
 
template<typename Rep , typename Period >
PublisherOptionsset_maximum_hold_time (std::chrono::duration< Rep, Period > v)
 Sets the maximum hold time for the messages. More...
 
std::size_t maximum_batch_message_count () const
 Sets the maximum hold time for the messages. More...
 
PublisherOptionsset_maximum_batch_message_count (std::size_t v)
 Set the maximum number of messages in a batch. More...
 
std::size_t maximum_batch_bytes () const
 Sets the maximum hold time for the messages. More...
 
PublisherOptionsset_maximum_batch_bytes (std::size_t v)
 Set the maximum size for the messages in a batch. More...
 
Publisher message ordering.

To guarantee messages are received by the service in the same order that the application gives them to a publisher, the client library needs to wait until a batch of messages is successfully delivered before sending the next batch, otherwise batches may arrive out of order as there is no guarantee the same channel or network path is used for each batch.

For applications that do not care about message ordering, this can limit the throughput. Therefore, the behavior is disabled by default.

bool message_ordering () const
 Return true if message ordering is enabled. More...
 
PublisherOptionsenable_message_ordering ()
 Enable message ordering. More...
 
PublisherOptionsdisable_message_ordering ()
 Disable message ordering. More...
 

Publisher flow control.

After a publisher flushes a batch of messages the batch is (obviously) not received immediately by the service.

While the batch remains pending it potentially consumes memory resources in the client (and/or the service).

Some applications may have constraints on the number of bytes and/or messages they can tolerate in this pending state, and may prefer to block or reject messages.

PublisherOptionsset_maximum_pending_bytes (std::size_t v)
 Flow control based on pending bytes. More...
 
PublisherOptionsset_maximum_pending_messages (std::size_t v)
 Flow control based on pending messages. More...
 
std::size_t maximum_pending_bytes () const
 Flow control based on pending bytes. More...
 
std::size_t maximum_pending_messages () const
 Flow control based on pending bytes. More...
 
bool full_publisher_ignored () const
 The current action for a full publisher. More...
 
bool full_publisher_rejects () const
 Flow control based on pending bytes. More...
 
bool full_publisher_blocks () const
 Flow control based on pending bytes. More...
 
PublisherOptionsset_full_publisher_ignored ()
 Ignore full publishers, continue as usual. More...
 
PublisherOptionsset_full_publisher_rejects ()
 Configure the publisher to reject new messages when full. More...
 
PublisherOptionsset_full_publisher_blocks ()
 Configure the publisher to block the caller when full. More...
 

Detailed Description

Configuration options for a Publisher.

These are largely used to control the batching configuration for a publisher. By default a publishers flushes a batch as soon as any of these conditions are met:

Applications developers should consult the Cloud Pub/Sub pricing page when selecting a batching configuration.

Example
namespace pubsub = ::google::cloud::pubsub;
using ::google::cloud::future;
using ::google::cloud::Options;
using ::google::cloud::StatusOr;
[](std::string project_id, std::string topic_id) {
auto topic = pubsub::Topic(std::move(project_id), std::move(topic_id));
// By default the publisher will flush a batch after 10ms, after it contains
// more than 100 message, or after it contains more than 1MiB of data,
// whichever comes first. This changes those defaults.
std::move(topic),
Options{}
.set<pubsub::MaxHoldTimeOption>(std::chrono::milliseconds(20))
.set<pubsub::MaxBatchBytesOption>(4 * 1024 * 1024L)
std::vector<future<void>> ids;
for (char const* data : {"1", "2", "3", "go!"}) {
ids.push_back(
publisher.Publish(pubsub::MessageBuilder().SetData(data).Build())
.then([data](future<StatusOr<std::string>> f) {
auto s = f.get();
if (!s) return;
std::cout << "Sent '" << data << "' (" << *s << ")\n";
}));
}
publisher.Flush();
// Block until they are actually sent.
for (auto& id : ids) id.get();
}
Constructs Message objects.
Definition: message.h:144
MessageBuilder & SetData(std::string data) &
Sets the message payload to data.
Definition: message.h:152
Message Build() &&
Creates a new message.
Definition: message.h:149
Publish messages to the Cloud Pub/Sub service.
Definition: publisher.h:98
void Flush()
Forcibly publishes any batched messages.
Definition: publisher.h:167
Objects of this class identify a Cloud Pub/Sub topic.
Definition: topic.h:37
std::shared_ptr< PublisherConnection > MakePublisherConnection(Topic topic, std::initializer_list< pubsub_internal::NonConstructible >)
Creates a new PublisherConnection object to work with Publisher.
Contains all the Cloud Pubsub C++ client types and functions.
Definition: ack_handler.cc:20
The maximum number of messages in a batch.
Definition: options.h:92
The maximum hold time for the messages.
Definition: options.h:78

Definition at line 61 of file publisher_options.h.

Constructor & Destructor Documentation

◆ PublisherOptions() [1/2]

google::cloud::pubsub::v1::PublisherOptions::PublisherOptions ( )
inline

Definition at line 63 of file publisher_options.h.

◆ PublisherOptions() [2/2]

google::cloud::pubsub::v1::PublisherOptions::PublisherOptions ( Options  opts)
explicit

Initialize the publisher options.

Expected options are any of the types in the PublisherOptionList

Note
Unrecognized options will be ignored. To debug issues with options set GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes in the environment and unexpected options will be logged.
Parameters
optsconfiguration options

Definition at line 23 of file publisher_options.cc.

Member Function Documentation

◆ disable_message_ordering()

PublisherOptions& google::cloud::pubsub::v1::PublisherOptions::disable_message_ordering ( )
inline

Disable message ordering.

See also
the documentation for the Publisher class for details.

Definition at line 187 of file publisher_options.h.

◆ enable_message_ordering()

PublisherOptions& google::cloud::pubsub::v1::PublisherOptions::enable_message_ordering ( )
inline

Enable message ordering.

See also
the documentation for the Publisher class for details.

Definition at line 177 of file publisher_options.h.

◆ full_publisher_blocks()

bool google::cloud::pubsub::v1::PublisherOptions::full_publisher_blocks ( ) const
inline

Flow control based on pending bytes.

Definition at line 234 of file publisher_options.h.

◆ full_publisher_ignored()

bool google::cloud::pubsub::v1::PublisherOptions::full_publisher_ignored ( ) const
inline

The current action for a full publisher.

Definition at line 226 of file publisher_options.h.

◆ full_publisher_rejects()

bool google::cloud::pubsub::v1::PublisherOptions::full_publisher_rejects ( ) const
inline

Flow control based on pending bytes.

Definition at line 230 of file publisher_options.h.

◆ maximum_batch_bytes()

std::size_t google::cloud::pubsub::v1::PublisherOptions::maximum_batch_bytes ( ) const
inline

Sets the maximum hold time for the messages.

Note
While this function accepts durations in arbitrary precision, the implementation depends on the granularity of your OS timers. It is possible that messages are held for slightly longer times than the value set here.
The first message in a batch starts the hold time counter. New messages do not extend the life of the batch. For example, if you have set the holding time to 10 milliseconds, start a batch with message 1, and publish a second message 5 milliseconds later, the second message will be flushed approximately 5 milliseconds after it is published.

Definition at line 135 of file publisher_options.h.

◆ maximum_batch_message_count()

std::size_t google::cloud::pubsub::v1::PublisherOptions::maximum_batch_message_count ( ) const
inline

Sets the maximum hold time for the messages.

Note
While this function accepts durations in arbitrary precision, the implementation depends on the granularity of your OS timers. It is possible that messages are held for slightly longer times than the value set here.
The first message in a batch starts the hold time counter. New messages do not extend the life of the batch. For example, if you have set the holding time to 10 milliseconds, start a batch with message 1, and publish a second message 5 milliseconds later, the second message will be flushed approximately 5 milliseconds after it is published.

Definition at line 116 of file publisher_options.h.

◆ maximum_hold_time()

std::chrono::microseconds google::cloud::pubsub::v1::PublisherOptions::maximum_hold_time ( ) const
inline

Sets the maximum hold time for the messages.

Note
While this function accepts durations in arbitrary precision, the implementation depends on the granularity of your OS timers. It is possible that messages are held for slightly longer times than the value set here.
The first message in a batch starts the hold time counter. New messages do not extend the life of the batch. For example, if you have set the holding time to 10 milliseconds, start a batch with message 1, and publish a second message 5 milliseconds later, the second message will be flushed approximately 5 milliseconds after it is published.

Definition at line 90 of file publisher_options.h.

◆ maximum_pending_bytes()

std::size_t google::cloud::pubsub::v1::PublisherOptions::maximum_pending_bytes ( ) const
inline

Flow control based on pending bytes.

Definition at line 218 of file publisher_options.h.

◆ maximum_pending_messages()

std::size_t google::cloud::pubsub::v1::PublisherOptions::maximum_pending_messages ( ) const
inline

Flow control based on pending bytes.

Definition at line 221 of file publisher_options.h.

◆ message_ordering()

bool google::cloud::pubsub::v1::PublisherOptions::message_ordering ( ) const
inline

Return true if message ordering is enabled.

Definition at line 170 of file publisher_options.h.

◆ set_full_publisher_blocks()

PublisherOptions& google::cloud::pubsub::v1::PublisherOptions::set_full_publisher_blocks ( )
inline

Configure the publisher to block the caller when full.

Definition at line 252 of file publisher_options.h.

◆ set_full_publisher_ignored()

PublisherOptions& google::cloud::pubsub::v1::PublisherOptions::set_full_publisher_ignored ( )
inline

Ignore full publishers, continue as usual.

Definition at line 240 of file publisher_options.h.

◆ set_full_publisher_rejects()

PublisherOptions& google::cloud::pubsub::v1::PublisherOptions::set_full_publisher_rejects ( )
inline

Configure the publisher to reject new messages when full.

Definition at line 246 of file publisher_options.h.

◆ set_maximum_batch_bytes()

PublisherOptions& google::cloud::pubsub::v1::PublisherOptions::set_maximum_batch_bytes ( std::size_t  v)
inline

Set the maximum size for the messages in a batch.

Note
Application developers should keep in mind that Cloud Pub/Sub sets limits on the size of a batch (10MB). The library makes no attempt to validate the value provided in this function.

Definition at line 149 of file publisher_options.h.

◆ set_maximum_batch_message_count()

PublisherOptions& google::cloud::pubsub::v1::PublisherOptions::set_maximum_batch_message_count ( std::size_t  v)
inline

Set the maximum number of messages in a batch.

Note
Application developers should keep in mind that Cloud Pub/Sub sets limits on the size of a batch (1,000 messages) The library makes no attempt to validate the value provided in this function.

Definition at line 130 of file publisher_options.h.

◆ set_maximum_hold_time()

template<typename Rep , typename Period >
PublisherOptions& google::cloud::pubsub::v1::PublisherOptions::set_maximum_hold_time ( std::chrono::duration< Rep, Period >  v)
inline

Sets the maximum hold time for the messages.

Note
While this function accepts durations in arbitrary precision, the implementation depends on the granularity of your OS timers. It is possible that messages are held for slightly longer times than the value set here.
The first message in a batch starts the hold time counter. New messages do not extend the life of the batch. For example, if you have set the holding time to 10 milliseconds, start a batch with message 1, and publish a second message 5 milliseconds later, the second message will be flushed approximately 5 milliseconds after it is published.

Definition at line 109 of file publisher_options.h.

◆ set_maximum_pending_bytes()

PublisherOptions& google::cloud::pubsub::v1::PublisherOptions::set_maximum_pending_bytes ( std::size_t  v)
inline

Flow control based on pending bytes.

Definition at line 207 of file publisher_options.h.

◆ set_maximum_pending_messages()

PublisherOptions& google::cloud::pubsub::v1::PublisherOptions::set_maximum_pending_messages ( std::size_t  v)
inline

Flow control based on pending messages.

Definition at line 213 of file publisher_options.h.