Namespace google::cloud::pubsub (2.33.0)

Contains all the Cloud Pub/Sub C++ client types and functions.

Classes

AckHandler

Defines the interface to acknowledge and reject messages.

BigQueryConfigBuilder

A helper class to build google::pubsub::v1::BigQueryConfig protos.

BlockingPublisher

Publish messages to the Cloud Pub/Sub service.

BlockingPublisherConnection

A connection to the Cloud Pub/Sub service to publish events.

CloudStorageConfigBuilder

A helper class to build google::pubsub::v1::CloudStorageConfig protos.

ExactlyOnceAckHandler

Defines the interface to acknowledge and reject messages.

LimitedErrorCountRetryPolicy

A retry policy based on counting errors.

LimitedTimeRetryPolicy

A retry policy based on elapsed time.

Message

The C++ representation for a Cloud Pub/Sub messages.

MessageBuilder

Constructs Message objects.

Publisher

Publish messages to the Cloud Pub/Sub service.

PublisherConnection

A connection to the Cloud Pub/Sub service to publish events.

PublisherOptions

Configuration options for a Publisher.

PullAckHandler

Defines the interface to acknowledge and reject messages.

PushConfigBuilder

Helper class to create google::pubsub::v1::PushConfig protos.

RetryPolicy

The base class for the Pub/Sub library retry policies.

Schema

Objects of this class identify a Cloud Pub/Sub schema.

SchemaServiceClient

Service for doing schema-related operations.

SchemaServiceConnection

The SchemaServiceConnection object for SchemaServiceClient.

SchemaServiceConnectionIdempotencyPolicy

SchemaServiceLimitedErrorCountRetryPolicy

A retry policy for SchemaServiceConnection based on counting errors.

SchemaServiceLimitedTimeRetryPolicy

A retry policy for SchemaServiceConnection based on elapsed time.

SchemaServiceRetryPolicy

The retry policy for SchemaServiceConnection.

Snapshot

Objects of this class identify a Cloud Pub/Sub snapshot.

SnapshotBuilder

Build a request to create a Cloud Pub/Sub snapshot.

Subscriber

Receive messages from the Cloud Pub/Sub service.

SubscriberConnection

A connection to the Cloud Pub/Sub service to receive events.

SubscriberOptions

Configure how a Subscriber handles incoming messages.

Subscription

Objects of this class identify a Cloud Pub/Sub subscription.

SubscriptionAdminClient

Performs subscription administrative operations in Cloud Pub/Sub.

SubscriptionAdminConnection

A connection to Cloud Pub/Sub for subscription-related administrative operations.

SubscriptionBuilder

Create a Cloud Pub/Sub subscription configuration.

Topic

Objects of this class identify a Cloud Pub/Sub topic.

TopicAdminClient

Performs topic admin operations in Cloud Pub/Sub.

TopicAdminConnection

A connection to Cloud Pub/Sub for topic-related administrative operations.

TopicBuilder

Builds requests to create or update a Cloud Pub/Sub topic.

Structs

BackoffPolicyOption

The backoff policy.

CompressionAlgorithmOption

Compression algorithm.

CompressionThresholdOption

Compression threshold.

ConnectionOptionsTraits

The Cloud Pub/Sub connection traits.

FullPublisherActionOption

The action taken by a full publisher.

MaxBatchBytesOption

The maximum size for the messages in a batch.

MaxBatchMessagesOption

The maximum number of messages in a batch.

MaxConcurrencyOption

The maximum callback concurrency.

MaxDeadlineExtensionOption

The maximum time by which the deadline for each incoming message is extended.

MaxDeadlineTimeOption

The maximum deadline for each incoming message.

MaxHoldTimeOption

The maximum hold time for the messages.

MaxOtelLinkCountOption

The maximum number of Open Telemetry span links.

MaxOutstandingBytesOption

The maximum number of outstanding bytes per streaming pull.

MaxOutstandingMessagesOption

The maximum number of outstanding messages per streaming pull.

MaxPendingBytesOption

The maximum size for pending messages.

MaxPendingMessagesOption

The maximum number of pending messages.

MessageOrderingOption

Publisher message ordering.

MinDeadlineExtensionOption

The minimum time by which the deadline for each incoming message is extended.

PullResponse

The response for a blocking pull.

RetryPolicyOption

The retry policy.

SchemaServiceBackoffPolicyOption

Use with google::cloud::Options to configure the backoff policy.

SchemaServiceConnectionIdempotencyPolicyOption

Use with google::cloud::Options to configure which operations are retried.

SchemaServiceRetryPolicyOption

Use with google::cloud::Options to configure the retry policy.

ShutdownPollingPeriodOption

How often the session polls for automatic shutdowns.

SubscriptionOption

Override the default subscription for a request.

Enums

FullPublisherAction

Actions taken by a full publisher.

Functions

MakeBlockingPublisherConnection(Options)

Creates a new BlockingPublisherConnection object to work with BlockingPublisher.

The BlockingPublisherConnection class is provided for applications wanting to mock the BlockingPublisher behavior in their tests. It is not intended for direct use.

Performance

Creating a new BlockingPublisherConnection is relatively expensive. This typically initiates connections to the service, and therefore these objects should be shared and reused when possible. Note that gRPC reuses existing OS resources (sockets) whenever possible, so applications may experience better performance on the second (and subsequent) calls to this function with the same Options from GrpcOptionList and CommonOptionList. However, this behavior is not guaranteed and applications should not rely on it.

See Also

BlockingPublisherConnection

Parameter
Name Description
opts

The options to use for this call. Expected options are any of the types in the following option lists.

Returns
Type Description
std::shared_ptr< BlockingPublisherConnection >

MakePublisherConnection(Topic, std::initializer_list< internal::NonConstructible >)

Creates a new PublisherConnection object to work with Publisher.

Parameters
Name Description
topic

Returns
Type Description
std::shared_ptr< PublisherConnection >

MakePublisherConnection(Topic, Options)

Creates a new PublisherConnection object to work with Publisher.

The PublisherConnection class is provided for applications wanting to mock the Publisher behavior in their tests. It is not intended for direct use.

Performance

Creating a new PublisherConnection is relatively expensive. This typically initiates connections to the service, and therefore these objects should be shared and reused when possible. Note that gRPC reuses existing OS resources (sockets) whenever possible, so applications may experience better performance on the second (and subsequent) calls to this function with the same Options from GrpcOptionList and CommonOptionList. However, this behavior is not guaranteed and applications should not rely on it.

See Also

PublisherConnection

Parameters
Name Description
topic

the Cloud Pub/Sub topic used by the returned PublisherConnection.

opts

The options to use for this call. Expected options are any of the types in the following option lists.

Returns
Type Description
std::shared_ptr< PublisherConnection >

MakePublisherConnection(Topic, PublisherOptions, ConnectionOptions, std::unique_ptr< RetryPolicy const >, std::unique_ptr< BackoffPolicy const >)

Creates a new PublisherConnection object to work with Publisher.

The PublisherConnection class is not intended for direct use in applications, it is provided for applications wanting to mock the Publisher behavior in their tests.

Performance

Creating a new PublisherConnection is relatively expensive. This typically initiate connections to the service, and therefore these objects should be shared and reused when possible. Note that gRPC reuses existing OS resources (sockets) whenever possible, so applications may experience better performance on the second (and subsequent) calls to this function with the identical values for options. However, this behavior is not guaranteed and applications should not rely on it.

See Also

PublisherConnection

Parameters
Name Description
topic

the Cloud Pub/Sub topic used by the returned PublisherConnection.

options

configure the batching policy and other parameters in the returned connection.

connection_options

(optional) general configuration for this connection, this type is also used to configure pubsub::Subscriber.

retry_policy

(optional) configure the retry loop.

backoff_policy

(optional) configure the backoff period between retries.

Returns
Type Description
std::shared_ptr< PublisherConnection >

MakeSchemaServiceConnection(Options)

A factory function to construct an object of type SchemaServiceConnection.

The returned connection object should not be used directly; instead it should be passed as an argument to the constructor of SchemaServiceClient.

The optional options argument may be used to configure aspects of the returned SchemaServiceConnection. Expected options are any of the types in the following option lists:

Parameter
Name Description
options

(optional) Configure the SchemaServiceConnection created by this function.

Returns
Type Description
std::shared_ptr< SchemaServiceConnection >

MakeDefaultSchemaServiceConnectionIdempotencyPolicy()

Returns
Type Description
std::unique_ptr< SchemaServiceConnectionIdempotencyPolicy >

MakeSubscriberConnection(Subscription, std::initializer_list< internal::NonConstructible >)

Creates a new SubscriberConnection object to work with Subscriber.

Parameters
Name Description
subscription

Returns
Type Description
std::shared_ptr< SubscriberConnection >

MakeSubscriberConnection(Subscription, Options)

Creates a new SubscriberConnection object to work with Subscriber.

The SubscriberConnection class is not intended for direct use in applications, it is provided for applications wanting to mock the Subscriber behavior in their tests.

Performance

Creating a new SubscriberConnection is relatively expensive. This typically initiate connections to the service, and therefore these objects should be shared and reused when possible. Note that gRPC reuses existing OS resources (sockets) whenever possible, so applications may experience better performance on the second (and subsequent) calls to this function with the same Options from GrpcOptionList and CommonOptionList. However, this behavior is not guaranteed and applications should not rely on it.

See Also

SubscriberConnection

Changing Retry Parameters Example
  namespace pubsub = ::google::cloud::pubsub;
 
using ::google::cloud::future;
 
using ::google::cloud::Options;
 
using ::google::cloud::StatusOr;
 
auto sample = [](std::string project_id, std::string subscription_id) {
   
// By default a subscriber will retry for 60 seconds, with an initial
   
// backoff of 100ms, a maximum backoff of 60 seconds, and the backoff will
   
// grow by 30% after each attempt. This changes those defaults.
   
auto subscriber = pubsub::Subscriber(pubsub::MakeSubscriberConnection(
        pubsub
::Subscription(std::move(project_id), std::move(subscription_id)),
       
Options{}
           
.set<pubsub::RetryPolicyOption>(
                pubsub
::LimitedTimeRetryPolicy(
                   
/*maximum_duration=*/std::chrono::minutes(1))
                   
.clone())
           
.set<pubsub::BackoffPolicyOption>(
                pubsub
::ExponentialBackoffPolicy(
                   
/*initial_delay=*/std::chrono::milliseconds(200),
                   
/*maximum_delay=*/std::chrono::seconds(10),
                   
/*scaling=*/2.0)
                   
.clone())));

   
auto session = subscriber.Subscribe(
       
[](pubsub::Message const& m, pubsub::AckHandler h) {
          std
::move(h).ack();
          std
::cout << "Received message " << m << "\n";
         
PleaseIgnoreThisSimplifiesTestingTheSamples();
       
});
   
return std::make_pair(subscriber, std::move(session));
 
};
Parameters
Name Description
subscription

the Cloud Pub/Sub subscription used by the returned connection.

opts

The options to use for this call. Expected options are any of the types in the following option lists.

Returns
Type Description
std::shared_ptr< SubscriberConnection >

MakeSubscriberConnection(Subscription, SubscriberOptions, ConnectionOptions, std::unique_ptr< pubsub::RetryPolicy const >, std::unique_ptr< pubsub::BackoffPolicy const >)

Creates a new SubscriberConnection object to work with Subscriber.

The SubscriberConnection class is not intended for direct use in applications, it is provided for applications wanting to mock the Subscriber behavior in their tests.

Performance

Creating a new SubscriberConnection is relatively expensive. This typically initiates connections to the service, and therefore these objects should be shared and reused when possible. Note that gRPC reuses existing OS resources (sockets) whenever possible, so applications may experience better performance on the second (and subsequent) calls to this function with the identical values for options. However, this behavior is not guaranteed and applications should not rely on it.

See Also

SubscriberConnection

Changing Retry Parameters Example
  namespace pubsub = ::google::cloud::pubsub;
 
using ::google::cloud::future;
 
using ::google::cloud::Options;
 
using ::google::cloud::StatusOr;
 
auto sample = [](std::string project_id, std::string subscription_id) {
   
// By default a subscriber will retry for 60 seconds, with an initial
   
// backoff of 100ms, a maximum backoff of 60 seconds, and the backoff will
   
// grow by 30% after each attempt. This changes those defaults.
   
auto subscriber = pubsub::Subscriber(pubsub::MakeSubscriberConnection(
        pubsub
::Subscription(std::move(project_id), std::move(subscription_id)),
       
Options{}
           
.set<pubsub::RetryPolicyOption>(
                pubsub
::LimitedTimeRetryPolicy(
                   
/*maximum_duration=*/std::chrono::minutes(1))
                   
.clone())
           
.set<pubsub::BackoffPolicyOption>(
                pubsub
::ExponentialBackoffPolicy(
                   
/*initial_delay=*/std::chrono::milliseconds(200),
                   
/*maximum_delay=*/std::chrono::seconds(10),
                   
/*scaling=*/2.0)
                   
.clone())));

   
auto session = subscriber.Subscribe(
       
[](pubsub::Message const& m, pubsub::AckHandler h) {
          std
::move(h).ack();
          std
::cout << "Received message " << m << "\n";
         
PleaseIgnoreThisSimplifiesTestingTheSamples();
       
});
   
return std::make_pair(subscriber, std::move(session));
 
};
```<aside class="deprecated"><b>Deprecated:</b>


Please use the `MakeSubscriberConnection` function which accepts [`google::cloud::Options`](xref:classgoogle_1_1cloud_1_1Options) instead.
</aside>
Parameters
Name Description
subscription

the Cloud Pub/Sub subscription used by the returned connection.

options

configure the flow control and other parameters in the returned connection.

connection_options

(optional) general configuration for this connection, this type is also used to configure pubsub::Publisher.

retry_policy

control for how long (or how many times) are retryable RPCs attempted.

backoff_policy

controls the backoff behavior between retry attempts, typically some form of exponential backoff with jitter.

Returns
Type Description
std::shared_ptr< SubscriberConnection >

MakeSubscriptionAdminConnection(std::initializer_list< internal::NonConstructible >)

Creates a new SubscriptionAdminConnection object to work with SubscriptionAdminClient.

Parameter
Name Description

Returns
Type Description
std::shared_ptr< SubscriptionAdminConnection >

MakeSubscriptionAdminConnection(Options)

Creates a new SubscriptionAdminConnection object to work with SubscriptionAdminClient.

The SubscriptionAdminConnection class is provided for applications wanting to mock the SubscriptionAdminClient behavior in their tests. It is not intended for direct use.

Performance

Creating a new SubscriptionAdminConnection is relatively expensive. This typically initiates connections to the service, and therefore these objects should be shared and reused when possible. Note that gRPC reuses existing OS resources (sockets) whenever possible, so applications may experience better performance on the second (and subsequent) calls to this function with the same Options from GrpcOptionList and CommonOptionList. However, this behavior is not guaranteed and applications should not rely on it.

See Also

SubscriptionAdminClient

Parameter
Name Description
opts

The options to use for this call. Expected options are any of the types in the following option lists.

Returns
Type Description
std::shared_ptr< SubscriptionAdminConnection >

MakeSubscriptionAdminConnection(ConnectionOptions const &, std::unique_ptr< pubsub::RetryPolicy const >, std::unique_ptr< pubsub::BackoffPolicy const >)

Creates a new SubscriptionAdminConnection object to work with SubscriptionAdminClient.

The SubscriptionAdminConnection class is not intended for direct use in applications, it is provided for applications wanting to mock the SubscriptionAdminClient behavior in their tests.

Performance

Creating a new SubscriptionAdminConnection is relatively expensive. This typically initiates connections to the service, and therefore these objects should be shared and reused when possible. Note that gRPC reuses existing OS resources (sockets) whenever possible, so applications may experience better performance on the second (and subsequent) calls to this function with the identical values for options. However, this behavior is not guaranteed and applications should not rely on it.

See Also

SubscriberConnection

Parameters
Name Description
options

(optional) configure the SubscriptionAdminConnection created by this function.

retry_policy

control for how long (or how many times) are retryable RPCs attempted.

backoff_policy

controls the backoff behavior between retry attempts, typically some form of exponential backoff with jitter.

Returns
Type Description
std::shared_ptr< SubscriptionAdminConnection >

MakeTopicAdminConnection(std::initializer_list< internal::NonConstructible >)

Creates a new TopicAdminConnection object to work with TopicAdminClient.

Parameter
Name Description

Returns
Type Description
std::shared_ptr< TopicAdminConnection >

MakeTopicAdminConnection(Options)

Creates a new TopicAdminConnection object to work with TopicAdminClient.

The TopicAdminConnection class is provided for applications wanting to mock the TopicAdminClient behavior in their tests. It is not intended for direct use.

Performance

Creating a new TopicAdminConnection is relatively expensive. This typically initiates connections to the service, and therefore these objects should be shared and reused when possible. Note that gRPC reuses existing OS resources (sockets) whenever possible, so applications may experience better performance on the second (and subsequent) calls to this function with the same Options from GrpcOptionList and CommonOptionList. However, this behavior is not guaranteed and applications should not rely on it.

See Also

TopicAdminClient

Parameter
Name Description
opts

The options to use for this call. Expected options are any of the types in the following option lists.

Returns
Type Description
std::shared_ptr< TopicAdminConnection >

MakeTopicAdminConnection(ConnectionOptions const &, std::unique_ptr< pubsub::RetryPolicy const >, std::unique_ptr< pubsub::BackoffPolicy const >)

Creates a new TopicAdminConnection object to work with TopicAdminClient.

The TopicAdminConnection class is provided for applications wanting to mock the TopicAdminClient behavior in their tests. It is not intended for direct use.

Performance

Creating a new TopicAdminConnection is relatively expensive. This typically initiate connections to the service, and therefore these objects should be shared and reused when possible. Note that gRPC reuses existing OS resources (sockets) whenever possible, so applications may experience better performance on the second (and subsequent) calls to this function with the identical values for options. However, this behavior is not guaranteed and applications should not rely on it.

See Also

TopicAdminClient

Parameters
Name Description
options

(optional) configure the TopicAdminConnection created by this function.

retry_policy

control for how long (or how many times) are retryable RPCs attempted.

backoff_policy

controls the backoff behavior between retry attempts, typically some form of exponential backoff with jitter.

Returns
Type Description
std::shared_ptr< TopicAdminConnection >

Type Aliases

ApplicationCallback

Alias Of: std::function< void(Message, AckHandler)>

Defines the interface for application-level callbacks.

Applications provide a callable compatible with this type to receive messages. They acknowledge (or reject) messages using AckHandler. This is a move-only type to support asynchronously acknowledgments.

ExactlyOnceApplicationCallback

Alias Of: std::function< void(pubsub::Message, ExactlyOnceAckHandler)>

Defines the interface for application-level callbacks with exactly-once delivery.

Applications provide a callable compatible with this type to receive messages. They acknowledge (or reject) messages using ExactlyOnceAckHandler. This is a move-only type to support asynchronous acknowledgments.

BackoffPolicy

Alias Of: ::google::cloud::internal::BackoffPolicy

The base class for backoff policies.

ExponentialBackoffPolicy

Alias Of: google::cloud::internal::ExponentialBackoffPolicy

A truncated exponential backoff policy with randomized periods.

ConnectionOptions

Alias Of: ::google::cloud::ConnectionOptions< ConnectionOptionsTraits >

Configure a connection for Cloud Pub/Sub services.

PubsubMessageDataType

Alias Of: std::decay_t< decltype(std::declval< google::pubsub::v1::PubsubMessage >().data())>

Defines the type for message data.

Inside Google some protobuf fields of type bytes are mapped to a different type than std::string. This is the case for message data. We use this type to automatically detect what is the representation for this field and use the correct mapping.

External users of the Cloud Pub/Sub C++ client library should treat this as a complicated typedef for std::string. We have no plans to change the type in the external version of the C++ client library for the foreseeable future. In the eventuality that we do decide to change the type, this would be a reason update the library major version number, and we would give users time to migrate.

In other words, external users of the Cloud Pub/Sub C++ client should simply write std::string where this type appears. For Google projects that must compile both inside and outside Google, this alias may be convenient.

PolicyOptionList

Alias Of: OptionList< RetryPolicyOption, BackoffPolicyOption >

The list of all "policy" options.

PublisherOptionList

Alias Of: OptionList< MaxHoldTimeOption, MaxBatchMessagesOption, MaxBatchBytesOption, MaxPendingMessagesOption, MaxPendingBytesOption, MessageOrderingOption, FullPublisherActionOption, CompressionThresholdOption, MaxOtelLinkCountOption >

The list of options specific to publishers.

ListSubscriptionsRange

Alias Of: google::cloud::internal::PaginationRange< google::pubsub::v1::Subscription >

An input range to stream Cloud Pub/Sub subscriptions.

This type models an input range of google::pubsub::v1::Subscription objects. Applications can make a single pass through the results.

ListSnapshotsRange

Alias Of: google::cloud::internal::PaginationRange< google::pubsub::v1::Snapshot >

An input range to stream Cloud Pub/Sub snapshots.

This type models an input range of google::pubsub::v1::Snapshot objects. Applications can make a single pass through the results.

ListTopicsRange

Alias Of: google::cloud::internal::PaginationRange< google::pubsub::v1::Topic >

An input range to stream Cloud Pub/Sub topics.

This type models an input range of google::pubsub::v1::Topic objects. Applications can make a single pass through the results.

ListTopicSubscriptionsRange

Alias Of: google::cloud::internal::PaginationRange< std::string >

An input range to stream the Cloud Pub/Sub subscriptions of a topic.

This type models an input range of std::string objects. Applications can make a single pass through the results.

ListTopicSnapshotsRange

Alias Of: google::cloud::internal::PaginationRange< std::string >

An input range to stream the Cloud Pub/Sub snapshots of a topic.

This type models an input range of std::string objects. Applications can make a single pass through the results.