Class BlockingPublisher (2.21.0)

Publish messages to the Cloud Pub/Sub service.

This class is used to publish messages to any given topic. It is intended for low-volume publishers. Applications sending less than one message per second may find this class easier to use than Publisher, which can handle thousands of messages per second.

See Also

https://cloud.google.com/pubsub for an overview of the Cloud Pub/Sub service.

Example
  namespace pubsub = ::google::cloud::pubsub;
  [](std::string project_id, std::string topic_id) {
    auto topic = pubsub::Topic(std::move(project_id), std::move(topic_id));
    auto publisher =
        pubsub::BlockingPublisher(pubsub::MakeBlockingPublisherConnection());
    auto id = publisher.Publish(
        topic, pubsub::MessageBuilder().SetData("Hello World!").Build());
    if (!id) throw std::move(id).status();
    std::cout << "Hello World successfully published on topic "
              << topic.FullName() << " with id " << *id << "\n";
  }
Performance

BlockingPublisher objects are relatively cheap to create, copy, and move. However, each BlockingPublisher object must be created with a std::shared_ptr<BlockingPublisherConnection>, which itself is relatively expensive to create. Therefore, connection instances should be shared when possible. See the MakeBlockingPublisherConnection() method and the BlockingPublisherConnection interface for more details.

Thread Safety

Instances of this class created via copy-construction or copy-assignment share the underlying pool of connections. Access to these copies via multiple threads is guaranteed to work. Two threads operating on the same instance of this class is not guaranteed to work.

Background Threads

This class uses the background threads configured via the Options from GrpcOptionList. Applications can create their own pool of background threads by (a) creating their own google::cloud::CompletionQueue, (b) passing this completion queue as a GrpcCompletionQueueOption, and (c) attaching any number of threads to the completion queue.

Error Handling

This class uses StatusOr<T> to report errors. When an operation fails to perform its work the returned StatusOr<T> contains the error details. If the ok() member function in the StatusOr<T> returns true then it contains the expected result. Please consult the google::cloud::StatusOr documentation for more details.

Constructors

BlockingPublisher(std::shared_ptr< BlockingPublisherConnection >, Options)

Parameters
NameDescription
connection std::shared_ptr< BlockingPublisherConnection >
opts Options

BlockingPublisher(BlockingPublisher const &)

Parameter
NameDescription
BlockingPublisher const &

BlockingPublisher(BlockingPublisher &&)

Parameter
NameDescription
BlockingPublisher &&

Operators

operator=(BlockingPublisher const &)

Parameter
NameDescription
BlockingPublisher const &
Returns
TypeDescription
BlockingPublisher &

operator=(BlockingPublisher &&)

Parameter
NameDescription
BlockingPublisher &&
Returns
TypeDescription
BlockingPublisher &

Functions

Publish(Topic, Message, Options)

Publishes the message on the topic topic.

Idempotency

This is a non-idempotent operation, but the client library will automatically retry RPCs that fail with transient errors. As Cloud Pub/Sub has "at least once" delivery semantics applications are expected to handle duplicate messages without problems. The application can disable retries by changing the retry policy, please see the example below.

Example
  namespace pubsub = ::google::cloud::pubsub;
  [](std::string project_id, std::string topic_id) {
    auto topic = pubsub::Topic(std::move(project_id), std::move(topic_id));
    auto publisher =
        pubsub::BlockingPublisher(pubsub::MakeBlockingPublisherConnection());
    auto id = publisher.Publish(
        topic, pubsub::MessageBuilder().SetData("Hello World!").Build());
    if (!id) throw std::move(id).status();
    std::cout << "Hello World successfully published on topic "
              << topic.FullName() << " with id " << *id << "\n";
  }
Example
  namespace pubsub = ::google::cloud::pubsub;
  [](std::string project_id, std::string topic_id) {
    auto topic = pubsub::Topic(std::move(project_id), std::move(topic_id));
    auto publisher =
        pubsub::BlockingPublisher(pubsub::MakeBlockingPublisherConnection());
    auto id = publisher.Publish(
        topic, pubsub::MessageBuilder().SetData("Hello World!").Build(),
        google::cloud::Options{}.set<pubsub::RetryPolicyOption>(
            pubsub::LimitedErrorCountRetryPolicy(/*maximum_failures=*/0)
                .clone()));
    if (!id) return;  // Without retries, errors are likely.
    std::cout << "Hello World successfully published on topic "
              << topic.FullName() << " with id " << *id << "\n";
  }
Parameters
NameDescription
topic Topic
message Message
opts Options
Returns
TypeDescription
StatusOr< std::string >

On success, the server-assigned ID of the message. IDs are guaranteed to be unique within the topic.