MongoDB C++ Driver  mongocxx-3.7.0
Public Types | Public Member Functions | List of all members
mongocxx::client_session Class Reference

Use a session for a sequence of operations, optionally with either causal consistency or snapshots. More...

#include <client_session.hpp>

Public Types

using with_transaction_cb = std::function< void(client_session *)>
 Helper to run a user-provided callback within a transaction. More...
 

Public Member Functions

 client_session (client_session &&) noexcept
 Move constructs a session.
 
client_sessionoperator= (client_session &&) noexcept
 Move assigns a session.
 
 ~client_session () noexcept
 Ends and destroys the session.
 
const class clientclient () const noexcept
 Gets the client that started this session.
 
const options::client_sessionoptions () const noexcept
 Gets the options this session was created with.
 
bsoncxx::document::view id () const noexcept
 Get the server-side "logical session ID" associated with this session, as a BSON document. More...
 
bsoncxx::document::view cluster_time () const noexcept
 Get the session's clusterTime, as a BSON document. More...
 
bsoncxx::types::b_timestamp operation_time () const noexcept
 Get the session's operationTime, as a BSON timestamp. More...
 
std::uint32_t server_id () const noexcept
 Get the server_id the session is pinned to. More...
 
transaction_state get_transaction_state () const noexcept
 Returns the current transaction state for this session.
 
bool get_dirty () const noexcept
 Returns whether or not this session is dirty.
 
void advance_cluster_time (const bsoncxx::document::view &cluster_time)
 Advance the cluster time for a session. More...
 
void advance_operation_time (const bsoncxx::types::b_timestamp &operation_time)
 Advance the session's operation time, expressed as a BSON timestamp. More...
 
void start_transaction (const stdx::optional< options::transaction > &transaction_opts={})
 Starts a transaction on the current client session. More...
 
void commit_transaction ()
 Commits a transaction on the current client session. More...
 
void abort_transaction ()
 Aborts a transaction on the current client session. More...
 

Detailed Description

Use a session for a sequence of operations, optionally with either causal consistency or snapshots.

Note that client_session is not thread-safe. See https://mongodb.github.io/mongo-cxx-driver/mongocxx-v3/thread-safety/ for more details.

See also
http://dochub.mongodb.org/core/causal-consistency

Member Typedef Documentation

◆ with_transaction_cb

Helper to run a user-provided callback within a transaction.

This method will start a new transaction on this client session, run the callback, then commit the transaction. If it cannot commit the transaction, the entire sequence may be retried, and the callback may be run multiple times.

If the user callback calls driver methods that run operations against the server that can throw an operation_exception (ex: collection::insert_one), the user callback should allow those exceptions to propagate up the stack so they can be caught and processed by the with_transaction helper.

Parameters
cbThe callback to run inside of a transaction.
opts(optional) The options to use to run the transaction.
Exceptions
mongocxx::operation_exceptionif there are errors completing the transaction.

Member Function Documentation

◆ abort_transaction()

void mongocxx::client_session::abort_transaction ( )

Aborts a transaction on the current client session.

Exceptions
mongocxx::operation_exceptionif the options are misconfigured or if there are other errors such as a session with no transaction in progress.

◆ advance_cluster_time()

void mongocxx::client_session::advance_cluster_time ( const bsoncxx::document::view cluster_time)

Advance the cluster time for a session.

Has an effect only if the new cluster time is greater than the session's current cluster time.

Use advance_operation_time() and advance_cluster_time() to copy the operationTime and clusterTime from another session, ensuring subsequent operations in this session are causally consistent with the last operation in the other session.

◆ advance_operation_time()

void mongocxx::client_session::advance_operation_time ( const bsoncxx::types::b_timestamp operation_time)

Advance the session's operation time, expressed as a BSON timestamp.

Has an effect only if the new operation time is greater than the session's current operation time.

Use advance_operation_time() and advance_cluster_time() to copy the operationTime and clusterTime from another session, ensuring subsequent operations in this session are causally consistent with the last operation in the other session.

◆ cluster_time()

bsoncxx::document::view mongocxx::client_session::cluster_time ( ) const
noexcept

Get the session's clusterTime, as a BSON document.

This is an opaque value suitable for passing to advance_cluster_time(). The document is empty if the session has not been used for any operation and you have not called advance_cluster_time(). This view is invalid after the session is destroyed.

◆ commit_transaction()

void mongocxx::client_session::commit_transaction ( )

Commits a transaction on the current client session.

Exceptions
mongocxx::operation_exceptionif the options are misconfigured, if there are network or other transient failures, or if there are other errors such as a session with no transaction in progress.

◆ id()

bsoncxx::document::view mongocxx::client_session::id ( ) const
noexcept

Get the server-side "logical session ID" associated with this session, as a BSON document.

This view is invalid after the session is destroyed.

◆ operation_time()

bsoncxx::types::b_timestamp mongocxx::client_session::operation_time ( ) const
noexcept

Get the session's operationTime, as a BSON timestamp.

This is an opaque value suitable for passing to advance_operation_time(). The timestamp is zero if the session has not been used for any operation and you have not called advance_operation_time().

◆ server_id()

std::uint32_t mongocxx::client_session::server_id ( ) const
noexcept

Get the server_id the session is pinned to.

The server_id is zero if the session is not pinned to a server.

◆ start_transaction()

void mongocxx::client_session::start_transaction ( const stdx::optional< options::transaction > &  transaction_opts = {})

Starts a transaction on the current client session.

Parameters
transaction_opts(optional) The options to use in the transaction.
Exceptions
mongocxx::operation_exceptionif the options are misconfigured, if there are network or other transient failures, or if there are other errors such as a session with a transaction already in progress.

The documentation for this class was generated from the following file: