Cloud Pub/Sub v1 API - Class SubscriberClient (3.11.0)

public abstract class SubscriberClient : IAsyncDisposable

Reference documentation and code samples for the Cloud Pub/Sub v1 API class SubscriberClient.

A PubSub subscriber that is associated with a specific SubscriptionName.

Inheritance

object > SubscriberClient

Implements

IAsyncDisposable

Derived Types

Namespace

Google.Cloud.PubSub.V1

Assembly

Google.Cloud.PubSub.V1.dll

Remarks

To receive messages, the StartAsync(SubscriptionHandler) method must be called, with a suitable message handler.

The message handler SubscriberClient.Reply states whether to acknowledge the message; if acknowledged then (under normal conditions) it will not be received on this subscription again.

But note that it is always possible to receive duplicate messages. This services guarantees "at least once" delivery, not "only once" delivery.

This class implements the IAsyncDisposable interface. However, it is recommended to create a single SubscriberClient instance, and use it throughout the lifetime of the application. If the SubscriberClient is registered in a dependency injection container, its DisposeAsync method will be called automatically.

Properties

DefaultAckDeadline

public static TimeSpan DefaultAckDeadline { get; }

The default message acknowledgement deadline of 60 seconds.

Property Value
TypeDescription
TimeSpan

DefaultAckDeadlineForExactlyOnceDelivery

public static TimeSpan DefaultAckDeadlineForExactlyOnceDelivery { get; }

The default message acknowledgement deadline of 60 seconds for exactly-once delivery subscriptions.

Property Value
TypeDescription
TimeSpan

DefaultAckExtensionWindow

public static TimeSpan DefaultAckExtensionWindow { get; }

The default message acknowledgement extension window of 15 seconds.

Property Value
TypeDescription
TimeSpan

DefaultDisposeTimeout

public static TimeSpan DefaultDisposeTimeout { get; }

The default DisposeTimeout of 5 seconds for the SubscriberClient.

Property Value
TypeDescription
TimeSpan

DefaultFlowControlSettings

public static FlowControlSettings DefaultFlowControlSettings { get; }

Default FlowControlSettings for SubscriberClient. Allows 1,000 outstanding messages; and 100Mb outstanding bytes.

Property Value
TypeDescription
FlowControlSettings

Default FlowControlSettings for SubscriberClient.

DefaultMaxTotalAckExtension

public static TimeSpan DefaultMaxTotalAckExtension { get; }

The default maximum total acknowledgement extension of 60 minutes.

Property Value
TypeDescription
TimeSpan

MaximumAckDeadline

public static TimeSpan MaximumAckDeadline { get; }

The service-defined maximum message acknowledgement deadline of 10 minutes.

Property Value
TypeDescription
TimeSpan

MinimumAckDeadline

public static TimeSpan MinimumAckDeadline { get; }

The service-defined minimum message acknowledgement deadline of 10 seconds.

Property Value
TypeDescription
TimeSpan

MinimumAckExtensionWindow

public static TimeSpan MinimumAckExtensionWindow { get; }

The minimum message acknowledgement extension window of 50 milliseconds.

Property Value
TypeDescription
TimeSpan

MinimumAckExtensionWindowForExactlyOnceDelivery

[Obsolete("Use DefaultAckDeadlineForExactlyOnceDelivery instead.")]
public static TimeSpan MinimumAckExtensionWindowForExactlyOnceDelivery { get; }

The minimum message acknowledgement extension window of 60 seconds for exactly once delivery subscriptions.

Property Value
TypeDescription
TimeSpan
Remarks

This property is deprecated. Use DefaultAckDeadlineForExactlyOnceDelivery instead.

MinimumLeaseExtensionDelay

public static TimeSpan MinimumLeaseExtensionDelay { get; }

The enforced 5 second minimum duration between obtaining a lease on a message and when a lease extension can be requested.

Property Value
TypeDescription
TimeSpan

SubscriptionName

public virtual SubscriptionName SubscriptionName { get; }

The associated SubscriptionName.

Property Value
TypeDescription
SubscriptionName

Methods

Create(SubscriptionName)

public static SubscriberClient Create(SubscriptionName subscriptionName)

Create a SubscriberClient instance associated with the specified SubscriptionName, using default settings.

Parameter
NameDescription
subscriptionNameSubscriptionName

The SubscriptionName to receive messages from.

Returns
TypeDescription
SubscriberClient

A SubscriberClient instance associated with the specified SubscriptionName.

Create(SubscriptionName, ClientCreationSettings, Settings)

[Obsolete("Use SubscriberClient.Create(SubscriptionName) to use the default settings, or SubscriberClientBuilder for customization.")]
public static SubscriberClient Create(SubscriptionName subscriptionName, SubscriberClient.ClientCreationSettings clientCreationSettings = null, SubscriberClient.Settings settings = null)

Create a SubscriberClient instance associated with the specified SubscriptionName. The default settings and clientCreationSettings are suitable for machines with high network bandwidth (e.g. Google Compute Engine instances). If running with more limited network bandwidth, some settings may need changing; especially AckDeadline. By default this method generates a gRPC channel per CPU core; if using a high-core-count machine and using many clients concurrently then this may need reducing; use the setting ClientCount.

Parameters
NameDescription
subscriptionNameSubscriptionName

The SubscriptionName to receive messages from.

clientCreationSettingsSubscriberClientClientCreationSettings

Optional. SubscriberClient.ClientCreationSettings specifying how to create SubscriberClients.

settingsSubscriberClientSettings

Optional. SubscriberClient.Settings for creating a SubscriberClient.

Returns
TypeDescription
SubscriberClient

A SubscriberClient instance associated with the specified SubscriptionName.

CreateAsync(SubscriptionName)

public static Task<SubscriberClient> CreateAsync(SubscriptionName subscriptionName)

Creates a SubscriberClient instance associated with the specified SubscriptionName, using default settings.

Parameter
NameDescription
subscriptionNameSubscriptionName

The SubscriptionName to receive messages from.

Returns
TypeDescription
TaskSubscriberClient

A SubscriberClient instance associated with the specified SubscriptionName.

CreateAsync(SubscriptionName, ClientCreationSettings, Settings)

[Obsolete("Use SubscriberClient.Create(SubscriptionName) to use the default settings, or SubscriberClientBuilder for customization.")]
public static Task<SubscriberClient> CreateAsync(SubscriptionName subscriptionName, SubscriberClient.ClientCreationSettings clientCreationSettings = null, SubscriberClient.Settings settings = null)

Create a SubscriberClient instance associated with the specified SubscriptionName. The default settings and clientCreationSettings are suitable for machines with high network bandwidth (e.g. Google Compute Engine instances). If running with more limited network bandwidth, some settings may need changing; especially AckDeadline. By default this method generates a gRPC channel per CPU core; if using a high-core-count machine and using many clients concurrently then this may need reducing; use the setting ClientCount.

Parameters
NameDescription
subscriptionNameSubscriptionName

The SubscriptionName to receive messages from.

clientCreationSettingsSubscriberClientClientCreationSettings

Optional. SubscriberClient.ClientCreationSettings specifying how to create SubscriberClients.

settingsSubscriberClientSettings

Optional. SubscriberClient.Settings for creating a SubscriberClient.

Returns
TypeDescription
TaskSubscriberClient

A SubscriberClient instance associated with the specified SubscriptionName.

DisposeAsync()

public virtual ValueTask DisposeAsync()

Disposes this SubscriberClient asynchronously.

Returns
TypeDescription
ValueTask
Remarks

This method asynchronously waits for the time interval as specified in the DisposeTimeout for the SubscriberClient to acknowledge the handled messages. If the clean shutdown is not complete after this time, it is aborted; this may leave some handled messages un-acknowledged. The time interval can be customized by setting the DisposeTimeout.

StartAsync(SubscriptionHandler)

public virtual Task StartAsync(SubscriptionHandler handler)

Starts receiving messages. The returned Task completes when either StopAsync(CancellationToken) is called or if an unrecoverable fault occurs. See StopAsync(CancellationToken) for more details. This method cannot be called more than once per SubscriberClient instance.

Parameter
NameDescription
handlerSubscriptionHandler

The handler that is passed all received messages and acknowledgement results.

Returns
TypeDescription
Task

A Task that completes when the subscriber is stopped, or if an unrecoverable error occurs.

StartAsync(Func<PubsubMessage, CancellationToken, Task<Reply>>)

public virtual Task StartAsync(Func<PubsubMessage, CancellationToken, Task<SubscriberClient.Reply>> handlerAsync)

Starts receiving messages. The returned Task completes when either StopAsync(CancellationToken) is called or if an unrecoverable fault occurs. See StopAsync(CancellationToken) for more details. This method cannot be called more than once per SubscriberClient instance.

Parameter
NameDescription
handlerAsyncFuncPubsubMessageCancellationTokenTaskSubscriberClientReply

The handler function that is passed all received messages. This function may be called on multiple threads concurrently. Return Ack from this function to acknowledge this message (implying it won't be received again); or return Nack to Not acknowledge this message (implying it will be received again). If this function throws any Exception, then it behaves as if it returned Nack.

Returns
TypeDescription
Task

A Task that completes when the subscriber is stopped, or if an unrecoverable error occurs.

StopAsync(CancellationToken)

public virtual Task StopAsync(CancellationToken hardStopToken)

Stop this SubscriberClient. Cancelling hardStopToken aborts the clean stop process, and may leave some handled messages un-acknowledged. The returned Task completes when all handled messages have been acknowledged. The returned Task faults if there is an unrecoverable error with the underlying service. The returned Task cancels if hardStopToken is cancelled.

Parameter
NameDescription
hardStopTokenCancellationToken

Cancel this CancellationToken to abort handlers and acknowledgement.

Returns
TypeDescription
Task

A Task that completes when all handled messages have been acknowledged; faults on unrecoverable service errors; or cancels if hardStopToken is cancelled.

StopAsync(TimeSpan)

public virtual Task StopAsync(TimeSpan timeout)

Stop this SubscriberClient. If timeout expires, the clean stop process will be aborted, and may leave some handled messages un-acknowledged. The returned Task completes when all handled messages have been acknowledged. The returned Task faults if there is an unrecoverable error with the underlying service. The returned Task cancels if timeout expires.

Parameter
NameDescription
timeoutTimeSpan

After this period, abort handling and acknowledging messages.

Returns
TypeDescription
Task

A Task that completes when all handled messages have been acknowledged; faults on unrecoverable service errors; or cancels if timeout expires.