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 | |
|---|---|
| Name | Description |
connection |
std::shared_ptr< BlockingPublisherConnection >
|
opts |
Options
|
BlockingPublisher(BlockingPublisher const &)
| Parameter | |
|---|---|
| Name | Description |
|
BlockingPublisher const &
|
BlockingPublisher(BlockingPublisher &&)
| Parameter | |
|---|---|
| Name | Description |
|
BlockingPublisher &&
|
Operators
operator=(BlockingPublisher const &)
| Parameter | |
|---|---|
| Name | Description |
|
BlockingPublisher const &
|
| Returns | |
|---|---|
| Type | Description |
BlockingPublisher & |
|
operator=(BlockingPublisher &&)
| Parameter | |
|---|---|
| Name | Description |
|
BlockingPublisher &&
|
| Returns | |
|---|---|
| Type | Description |
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 | |
|---|---|
| Name | Description |
topic |
Topic
|
message |
Message
|
opts |
Options
|
| Returns | |
|---|---|
| Type | Description |
StatusOr< std::string > |
On success, the server-assigned ID of the message. IDs are guaranteed to be unique within the topic. |