Google Cloud Pub/Sub C++ Client  2.4.0
A C++ Client Library for Google Cloud Pub/Sub
Classes | Public Member Functions | List of all members
google::cloud::pubsub::ExactlyOnceAckHandler Class Reference

Defines the interface to acknowledge and reject messages. More...

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

Classes

class  Impl
 Allow applications to mock an ExactlyOnceAckHandler. More...
 

Public Member Functions

 ~ExactlyOnceAckHandler ()
 
 ExactlyOnceAckHandler (ExactlyOnceAckHandler &&)=default
 
ExactlyOnceAckHandleroperator= (ExactlyOnceAckHandler &&)=default
 
future< Statusack () &&
 Acknowledges the message associated with this handler. More...
 
future< Statusnack () &&
 Rejects the message associated with this handler. More...
 
std::int32_t delivery_attempt () const
 Returns the approximate number of times that Cloud Pub/Sub has attempted to deliver the associated message to a subscriber. More...
 
 ExactlyOnceAckHandler (std::unique_ptr< Impl > impl)
 Applications may use this constructor in their mocks. More...
 

Detailed Description

Defines the interface to acknowledge and reject messages.

When applications register a callback to receive Pub/Sub messages the callback must be able to receive both a pubsub::Message and its associated pubsub::ExactlyOnceAckHandler. Actions on a pubsub::ExactlyOnceAckHandler always affect the same message received in the callback. Applications cannot create standalone handlers (except in unit tests via mocks).

This interface allows applications to acknowledge and reject messages that are provided by the Cloud Pub/Sub C++ client library to the application. Note that this class is move-able, to support applications that process messages asynchronously. However, this class is not copy-able, because messages can only be acknowledged or rejected exactly once.

Thread Safety
This class is thread compatible, only one thread should call non-const member functions of this class at a time. Note that because the non-const member functions are && overloads the application can only call ack() or nack() exactly once, and only one of them.

Definition at line 49 of file exactly_once_ack_handler.h.

Constructor & Destructor Documentation

◆ ~ExactlyOnceAckHandler()

google::cloud::pubsub::ExactlyOnceAckHandler::~ExactlyOnceAckHandler ( )

◆ ExactlyOnceAckHandler() [1/2]

google::cloud::pubsub::ExactlyOnceAckHandler::ExactlyOnceAckHandler ( ExactlyOnceAckHandler &&  )
default

◆ ExactlyOnceAckHandler() [2/2]

google::cloud::pubsub::ExactlyOnceAckHandler::ExactlyOnceAckHandler ( std::unique_ptr< Impl impl)
inlineexplicit

Applications may use this constructor in their mocks.

Definition at line 130 of file exactly_once_ack_handler.h.

Member Function Documentation

◆ ack()

future<Status> google::cloud::pubsub::ExactlyOnceAckHandler::ack ( ) &&
inline

Acknowledges the message associated with this handler.

Idempotency
If exactly-once is enabled in the subscription, the client library will retry this operation in the background until it succeeds, fails with a permanent error, or the ack id has become unusable (all ack ids are unusable after 10 minutes). The returned future is satisfied when the retry loop completes.

If exactly-once is not enabled, the request is handled on a best-effort basis.

If the future is satisfied with an Okay Status and exactly-once delivery is enabled in the subscription, then the message will not be resent by Cloud Pub/Sub. We remind the reader that Cloud Pub/Sub defaults to "at least once" delivery, that is, without exactly-once delivery, the message may be resent even after the future is satisfied with an Okay Status.

If the future is satisfied with an error, it is possible that Cloud Pub/Sub never received the acknowledgement, and will resend the message.

Definition at line 79 of file exactly_once_ack_handler.h.

◆ delivery_attempt()

std::int32_t google::cloud::pubsub::ExactlyOnceAckHandler::delivery_attempt ( ) const
inline

Returns the approximate number of times that Cloud Pub/Sub has attempted to deliver the associated message to a subscriber.

Definition at line 107 of file exactly_once_ack_handler.h.

◆ nack()

future<Status> google::cloud::pubsub::ExactlyOnceAckHandler::nack ( ) &&
inline

Rejects the message associated with this handler.

Idempotency
If exactly-once is enabled in the subscription, the client library will retry this operation in the background until it succeeds, fails with a permanent error, or the ack id has become unusable (all ack ids are unusable after 10 minutes). The returned future is satisfied when the retry loop completes.

If exactly-once is not enabled, the request is handled on a best-effort basis.

In any case, Cloud Pub/Sub will eventually resend the message. It might do so sooner if the operation succeeds.

Definition at line 100 of file exactly_once_ack_handler.h.

◆ operator=()

ExactlyOnceAckHandler& google::cloud::pubsub::ExactlyOnceAckHandler::operator= ( ExactlyOnceAckHandler &&  )
default