google::cloud::pubsub::BlockingPublisher Class Reference

Publish messages to the Cloud Pub/Sub service. More...

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

Public Member Functions
	BlockingPublisher (std::shared_ptr< BlockingPublisherConnection > connection, Options opts={})
	BlockingPublisher (BlockingPublisher const &)=default
BlockingPublisher &	operator= (BlockingPublisher const &)=default
	BlockingPublisher (BlockingPublisher &&)=default
BlockingPublisher &	operator= (BlockingPublisher &&)=default
StatusOr< std::string >	Publish (Topic topic, Message message, Options opts={})
	Publishes the message on the topic topic. More...

Friends
bool	operator== (BlockingPublisher const &a, BlockingPublisher const &b)
bool	operator!= (BlockingPublisher const &a, BlockingPublisher const &b)

Detailed Description

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.

Constructor & Destructor Documentation

BlockingPublisher() [1/3]

google::cloud::pubsub::BlockingPublisher::BlockingPublisher ( std::shared_ptr< BlockingPublisherConnection >  connection, Options  opts = {}  )

explicit

BlockingPublisher() [2/3]

google::cloud::pubsub::BlockingPublisher::BlockingPublisher ( BlockingPublisher const &  )

default

BlockingPublisher() [3/3]

google::cloud::pubsub::BlockingPublisher::BlockingPublisher ( BlockingPublisher &&  )

default

Member Function Documentation

operator=() [1/2]

BlockingPublisher & google::cloud::pubsub::BlockingPublisher::operator= ( BlockingPublisher &&  )

default

operator=() [2/2]

BlockingPublisher & google::cloud::pubsub::BlockingPublisher::operator= ( BlockingPublisher const &  )

default

Publish()

StatusOr< std::string > google::cloud::pubsub::BlockingPublisher::Publish	(	Topic	topic,
		Message	message,
		Options	opts = {}
	)

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";
  }

Returns

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

Friends And Related Function Documentation

operator!=

bool operator!= ( BlockingPublisher const &  a, BlockingPublisher const &  b  )

friend

operator==

bool operator== ( BlockingPublisher const &  a, BlockingPublisher const &  b  )

friend