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 >
PublisherOptions &	set_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
PublisherOptions &	set_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
PublisherOptions &	set_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...
PublisherOptions &	enable_message_ordering ()
	Enable message ordering. More...
PublisherOptions &	disable_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.
PublisherOptions &	set_maximum_pending_bytes (std::size_t v)
	Flow control based on pending bytes. More...
PublisherOptions &	set_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...
PublisherOptions &	set_full_publisher_ignored ()
	Ignore full publishers, continue as usual. More...
PublisherOptions &	set_full_publisher_rejects ()
	Configure the publisher to reject new messages when full. More...
PublisherOptions &	set_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:

• 10ms after the first message is put in the batch,
• when the batch contains 100 messages or more,
• when the batch contains 1MiB of data or more.

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();
  }

Constructor & Destructor Documentation

PublisherOptions() [1/2]

google::cloud::pubsub::PublisherOptions::PublisherOptions

(

)

Deprecated:

Use google::cloud::Options{} instead.

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

opts	configuration 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.

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.

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.

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.

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.

maximum_batch_bytes()

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

inline

Deprecated:

Use google::cloud::Options{} and MaxBatchBytesOption instead.

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.

maximum_hold_time()

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

inline

Deprecated:

Use google::cloud::Options{} and MaxHoldTimeOption instead.

maximum_pending_bytes()

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

inline

Deprecated:

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

maximum_pending_messages()

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

inline

Deprecated:

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

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.

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.

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.

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.

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.

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.

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.

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.

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.