#include <mongocxx/v_noabi/mongocxx/client_session.hpp>

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://www.mongodb.com/docs/languages/cpp/cpp-driver/current/thread-safety/ for more details.

See also

https://www.mongodb.com/docs/manual/core/read-isolation-consistency-recency/#causal-consistency

Public Types
using	with_transaction_cb = std::function<void MONGOCXX_ABI_CDECL(client_session*)>
	Represents a callback invoked within a transaction.

Public Member Functions
	client_session (client_session &&) noexcept
	Move constructs a session.

	~client_session () noexcept
	Ends and destroys the session.

void	abort_transaction ()
	Aborts a transaction on the current client session.

void	advance_cluster_time (const bsoncxx::v_noabi::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.

void	advance_operation_time (const bsoncxx::v_noabi::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.

const mongocxx::v_noabi::client &	client () const noexcept
	Gets the client that started this session.

bsoncxx::v_noabi::document::view	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.

void	commit_transaction ()
	Commits a transaction on the current client session.

bool	get_dirty () const noexcept
	Returns whether or not this session is dirty.

transaction_state	get_transaction_state () const noexcept
	Returns the current transaction state for this session.

bsoncxx::v_noabi::document::view	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.

bsoncxx::v_noabi::types::b_timestamp	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().

client_session &	operator= (client_session &&) noexcept
	Move assigns a session.

const options::client_session &	options () const noexcept
	Gets the options this session was created with.

std::uint32_t	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.

void	start_transaction (const bsoncxx::v_noabi::stdx::optional< options::transaction > &transaction_opts={})
	Starts a transaction on the current client session.

void	with_transaction (with_transaction_cb cb, options::transaction opts={})
	Helper to run a user-provided callback within a transaction.

Member Typedef Documentation

◆ with_transaction_cb

using mongocxx::v_noabi::client_session::with_transaction_cb = std::function<void MONGOCXX_ABI_CDECL(client_session*)>

Represents a callback invoked within a transaction.

Constructor & Destructor Documentation

◆ client_session()

mongocxx::v_noabi::client_session::client_session ( client_session && )

noexcept

Move constructs a session.

◆ ~client_session()

mongocxx::v_noabi::client_session::~client_session ( )

noexcept

Ends and destroys the session.

Member Function Documentation

◆ abort_transaction()

void mongocxx::v_noabi::client_session::abort_transaction ( )

Aborts a transaction on the current client session.

Exceptions

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

◆ advance_cluster_time()

void mongocxx::v_noabi::client_session::advance_cluster_time ( const bsoncxx::v_noabi::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::v_noabi::client_session::advance_operation_time ( const bsoncxx::v_noabi::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.

◆ client()

const mongocxx::v_noabi::client & mongocxx::v_noabi::client_session::client ( ) const

noexcept

Gets the client that started this session.

◆ cluster_time()

bsoncxx::v_noabi::document::view mongocxx::v_noabi::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::v_noabi::client_session::commit_transaction ( )

Commits a transaction on the current client session.

Exceptions

mongocxx::v_noabi::operation_exception if 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.

◆ get_dirty()

bool mongocxx::v_noabi::client_session::get_dirty ( ) const

noexcept

Returns whether or not this session is dirty.

◆ get_transaction_state()

transaction_state mongocxx::v_noabi::client_session::get_transaction_state ( ) const

noexcept

Returns the current transaction state for this session.

◆ id()

bsoncxx::v_noabi::document::view mongocxx::v_noabi::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::v_noabi::types::b_timestamp mongocxx::v_noabi::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().

◆ operator=()

client_session & mongocxx::v_noabi::client_session::operator= ( client_session && )

noexcept

Move assigns a session.

◆ options()

const options::client_session & mongocxx::v_noabi::client_session::options ( ) const

noexcept

Gets the options this session was created with.

◆ server_id()

std::uint32_t mongocxx::v_noabi::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::v_noabi::client_session::start_transaction ( const bsoncxx::v_noabi::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::v_noabi::operation_exception if 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.

◆ with_transaction()

void mongocxx::v_noabi::client_session::with_transaction	(	with_transaction_cb	cb,
		options::transaction	opts = {} )

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.

This method has an internal non-adjustable time limit of 120 seconds, including all retries.

If the user callback invokes driver methods that run operations against the server which could throw an operation_exception, the user callback MUST allow those exceptions to propagate up the stack so they can be caught and processed by the with_transaction() helper.

For example, a callback that invokes collection::insert_one may encounter a "duplicate key" error with accompanying server-side transaction abort. If this error were not seen by the with_transaction() helper, the entire transaction would retry repeatedly until the overall time limit expires.

Parameters

cb	The callback to run inside of a transaction.
opts	(optional) The options to use to run the transaction.

Exceptions

mongocxx::v_noabi::operation_exception if there are errors completing the transaction.

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

mongocxx/v_noabi/mongocxx/client_session.hpp

Description

Public Types

Public Member Functions

Member Typedef Documentation

◆ with_transaction_cb

Constructor & Destructor Documentation

◆ client_session()

◆ ~client_session()

Member Function Documentation

◆ abort_transaction()

◆ advance_cluster_time()

◆ advance_operation_time()

◆ client()

◆ cluster_time()

◆ commit_transaction()

◆ get_dirty()

◆ get_transaction_state()

◆ id()

◆ operation_time()

◆ operator=()

◆ options()

◆ server_id()

◆ start_transaction()

◆ with_transaction()