Google Cloud Pub/Sub C++ Client  1.42.0
A C++ Client Library for Google Cloud Pub/Sub
Public Member Functions | List of all members
google::cloud::pubsub::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
 
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
 
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
 
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
 
std::size_t maximum_pending_messages () const
 
bool full_publisher_ignored () const
 The current action for a full publisher. More...
 
bool full_publisher_rejects () const
 The current action for a full publisher. More...
 
bool full_publisher_blocks () const
 The current action for a full publisher. 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.

Deprecated:
We recommend you use google::cloud::Options and pass the options to MakePublisherConnection().
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.
auto publisher = pubsub::Publisher(pubsub::MakePublisherConnection(
std::move(topic),
Options{}
.set<pubsub::MaxHoldTimeOption>(std::chrono::milliseconds(20))
.set<pubsub::MaxBatchBytesOption>(4 * 1024 * 1024L)
.set<pubsub::MaxBatchMessagesOption>(200)));
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();
}
std::shared_ptr< PublisherConnection > MakePublisherConnection(Topic topic, std::initializer_list< internal::NonConstructible >)
Creates a new PublisherConnection object to work with Publisher.

Definition at line 64 of file publisher_options.h.

Constructor & Destructor Documentation

◆ PublisherOptions() [1/2]

google::cloud::pubsub::PublisherOptions::PublisherOptions ( )

◆ PublisherOptions() [2/2]

google::cloud::pubsub::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
Deprecated:
Use google::cloud::Options{} instead.

Member Function Documentation

◆ disable_message_ordering()

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

Disable message ordering.

Deprecated:
Use google::cloud::Options{} and MessageOrderingOption instead.
See also
the documentation for the Publisher class for details.

Definition at line 238 of file publisher_options.h.

◆ enable_message_ordering()

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

Enable message ordering.

Deprecated:
Use google::cloud::Options{} and MessageOrderingOption instead.
See also
the documentation for the Publisher class for details.

Definition at line 223 of file publisher_options.h.

◆ full_publisher_blocks()

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

The current action for a full publisher.

Deprecated:
Use google::cloud::Options{} and FullPublisherActionOption instead.

Definition at line 333 of file publisher_options.h.

◆ full_publisher_ignored()

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

The current action for a full publisher.

Deprecated:
Use google::cloud::Options{} and FullPublisherActionOption instead.

Definition at line 307 of file publisher_options.h.

◆ full_publisher_rejects()

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

The current action for a full publisher.

Deprecated:
Use google::cloud::Options{} and FullPublisherActionOption instead.

Definition at line 320 of file publisher_options.h.

◆ maximum_batch_bytes()

std::size_t google::cloud::pubsub::PublisherOptions::maximum_batch_bytes ( ) const
inline
Deprecated:
Use google::cloud::Options{} and MaxBatchBytesOption instead.

Definition at line 164 of file publisher_options.h.

◆ maximum_batch_message_count()

std::size_t google::cloud::pubsub::PublisherOptions::maximum_batch_message_count ( ) const
inline
Deprecated:
Use google::cloud::Options{} and MaxBatchMessagesOption instead.

Definition at line 136 of file publisher_options.h.

◆ maximum_hold_time()

std::chrono::microseconds google::cloud::pubsub::PublisherOptions::maximum_hold_time ( ) const
inline
Deprecated:
Use google::cloud::Options{} and MaxHoldTimeOption instead.

Definition at line 102 of file publisher_options.h.

◆ maximum_pending_bytes()

std::size_t google::cloud::pubsub::PublisherOptions::maximum_pending_bytes ( ) const
inline
Deprecated:
Use google::cloud::Options{} and MaxPendingBytesOption instead.

Definition at line 287 of file publisher_options.h.

◆ maximum_pending_messages()

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

◆ message_ordering()

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

Return true if message ordering is enabled.

Deprecated:
Use google::cloud::Options{} and MessageOrderingOption instead.

Definition at line 211 of file publisher_options.h.

◆ set_full_publisher_blocks()

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

Configure the publisher to block the caller when full.

Deprecated:
Use google::cloud::Options{} and FullPublisherActionOption instead.

Definition at line 372 of file publisher_options.h.

◆ set_full_publisher_ignored()

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

Ignore full publishers, continue as usual.

Deprecated:
Use google::cloud::Options{} and FullPublisherActionOption instead.

Definition at line 346 of file publisher_options.h.

◆ set_full_publisher_rejects()

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

Configure the publisher to reject new messages when full.

Deprecated:
Use google::cloud::Options{} and FullPublisherActionOption instead.

Definition at line 359 of file publisher_options.h.

◆ set_maximum_batch_bytes()

PublisherOptions& google::cloud::pubsub::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.
Deprecated:
Use google::cloud::Options{} and MaxBatchBytesOption instead.

Definition at line 183 of file publisher_options.h.

◆ set_maximum_batch_message_count()

PublisherOptions& google::cloud::pubsub::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.
Deprecated:
Use google::cloud::Options{} and MaxBatchMessagesOption instead.

Definition at line 155 of file publisher_options.h.

◆ set_maximum_hold_time()

template<typename Rep , typename Period >
PublisherOptions& google::cloud::pubsub::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.
Deprecated:
Use google::cloud::Options{} and MaxHoldTimeOption instead.

Definition at line 125 of file publisher_options.h.

◆ set_maximum_pending_bytes()

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

Flow control based on pending bytes.

Deprecated:
Use google::cloud::Options{} and MaxPendingBytesOption instead.

Definition at line 265 of file publisher_options.h.

◆ set_maximum_pending_messages()

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

Flow control based on pending messages.

Deprecated:
Use google::cloud::Options{} and MaxPendingMessagesOption instead.

Definition at line 278 of file publisher_options.h.