mongocxx::v1::client_session Class Reference

#include <mongocxx/v1/client_session.hpp>

Description

A MongoDB client session.

See also

• Read Isolation, Consistency, and Recency (MongoDB Manual)
• Server Sessions (MongoDB Manual)

Attention

This feature is experimental! It is not ready for use!

Classes
class	options
	Options for mongocxx::v1::client_session. More...

Public Types
enum class	transaction_state
	The state of an associated transaction. More...
using	with_transaction_cb = std::function<void (client_session&)>
	The callback function to invoke within a standalone transaction.

Public Member Functions
	client_session (client_session &&other) noexcept
	Move constructor.
	client_session (client_session const &)=delete
	This class is not copyable.
	~client_session ()
	Destroy this object.
void	abort_transaction ()
	Abort the current transaction.
void	advance_cluster_time (bsoncxx::v1::document::view v)
	Advance the "clusterTime" value for this session.
void	advance_operation_time (bsoncxx::v1::types::b_timestamp v)
	Advance the "operationTime" value for this session.
v1::client const &	client () const
	Return the associated client object.
bsoncxx::v1::document::view	cluster_time () const
	Return this session's current "clusterTime" value.
void	commit_transaction ()
	Commit the current transaction.
bool	get_dirty () const
	Return true when the current session is dirty.
transaction_state	get_transaction_state () const
	Return the current transaction state.
bsoncxx::v1::document::view	id () const
	Return the current "lsid" (logical session ID).
bsoncxx::v1::types::b_timestamp	operation_time () const
	Return this session's current "operationTime" value.
client_session &	operator= (client_session &&other) noexcept
	Move assignment.
client_session &	operator= (client_session const &)=delete
	This class is not copyable.
options	opts () const
	Return the options used to create this client session.
std::uint32_t	server_id () const
	Return the ID of the current pinned server.
void	start_transaction ()
	Start a new transaction.
void	start_transaction (v1::transaction_options const &opts)
	Start a new transaction using opts instead of default transaction options.
void	with_transaction (with_transaction_cb const &fn)
	Equivalent to with_transaction(with_transaction_cb const& fn, v1::transaction_options const& opts) with a default-initialized v1::transaction_options.
void	with_transaction (with_transaction_cb const &fn, v1::transaction_options const &opts)
	Start and commit a new standalone transaction using fn.

Member Typedef Documentation

with_transaction_cb

using mongocxx::v1::client_session::with_transaction_cb = std::function<void (client_session&)>

The callback function to invoke within a standalone transaction.

this is passed to the callback function and must be forwarded to operations within the callback function.

The callback function may be invoked multiple times as part of retry attempt behavior.

Warning

The callback function MUST allow any mongocxx::v1::server_error exceptions thrown by an operation within the callback function to propagate out of the callback function for correct retry attempt behavior. The callback function MUST NOT attempt to manually retry operations.

Member Enumeration Documentation

transaction_state

enum class mongocxx::v1::client_session::transaction_state

strong

The state of an associated transaction.

Attention

This feature is experimental! It is not ready for use!

Enumerator
k_transaction_none	No associated transaction.
k_transaction_starting	An associated transaction has started.
k_transaction_in_progress	The associated transaction is in progress.
k_transaction_committed	The associated transaction was committed.
k_transaction_aborted	The associated transaction was aborted.

Constructor & Destructor Documentation

~client_session()

mongocxx::v1::client_session::~client_session

(

)

Destroy this object.

Warning

Invalidates all associated views and references.

client_session() [1/2]

mongocxx::v1::client_session::client_session ( client_session && other )

noexcept

Move constructor.

Postconditions:

• other is in an assign-or-destroy-only state.

client_session() [2/2]

mongocxx::v1::client_session::client_session ( client_session const & )

delete

This class is not copyable.

Member Function Documentation

abort_transaction()

void mongocxx::v1::client_session::abort_transaction

(

)

Abort the current transaction.

Exceptions

mongocxx::v1::exception

when a client-side error is encountered.

advance_cluster_time()

void mongocxx::v1::client_session::advance_cluster_time

(

bsoncxx::v1::document::view

v

)

Advance the "clusterTime" value for this session.

Parameters

v	A "clusterTime" value obtained by a prior call to cluster_time.

advance_operation_time()

void mongocxx::v1::client_session::advance_operation_time

(

bsoncxx::v1::types::b_timestamp

v

)

Advance the "operationTime" value for this session.

Parameters

v	An "operationTime" value obtained by a prior call to operation_time.

client()

v1::client const & mongocxx::v1::client_session::client

(

)

const

Return the associated client object.

cluster_time()

bsoncxx::v1::document::view mongocxx::v1::client_session::cluster_time

(

)

const

Return this session's current "clusterTime" value.

Returns

Empty when not available.

commit_transaction()

void mongocxx::v1::client_session::commit_transaction

(

)

Commit the current transaction.

Exceptions

mongocxx::v1::server_error	when a server-side error is encountered and a raw server error is available.
mongocxx::v1::exception	for all other runtime errors.

get_dirty()

bool mongocxx::v1::client_session::get_dirty

(

)

const

Return true when the current session is dirty.

get_transaction_state()

transaction_state mongocxx::v1::client_session::get_transaction_state

(

)

const

Return the current transaction state.

id()

bsoncxx::v1::document::view mongocxx::v1::client_session::id

(

)

const

Return the current "lsid" (logical session ID).

Returns

Empty when one is not available.

operation_time()

bsoncxx::v1::types::b_timestamp mongocxx::v1::client_session::operation_time

(

)

const

Return this session's current "operationTime" value.

Returns

Default-initialized when not available.

operator=() [1/2]

client_session & mongocxx::v1::client_session::operator= ( client_session && other )

noexcept

Move assignment.

Postconditions:

• other is in an assign-or-destroy-only state.

operator=() [2/2]

client_session & mongocxx::v1::client_session::operator= ( client_session const & )

delete

This class is not copyable.

opts()

options mongocxx::v1::client_session::opts

(

)

const

Return the options used to create this client session.

server_id()

std::uint32_t mongocxx::v1::client_session::server_id

(

)

const

Return the ID of the current pinned server.

start_transaction() [1/2]

void mongocxx::v1::client_session::start_transaction

(

)

Start a new transaction.

Default transaction options are applied to the new transaction.

Exceptions

mongocxx::v1::exception

when a client-side error is encountered.

start_transaction() [2/2]

void mongocxx::v1::client_session::start_transaction

(

v1::transaction_options const &

opts

)

Start a new transaction using opts instead of default transaction options.

Exceptions

mongocxx::v1::exception

when a client-side error is encountered.

with_transaction() [1/2]

void mongocxx::v1::client_session::with_transaction

(

with_transaction_cb const &

fn

)

Equivalent to with_transaction(with_transaction_cb const& fn, v1::transaction_options const& opts) with a default-initialized v1::transaction_options.

with_transaction() [2/2]

void mongocxx::v1::client_session::with_transaction	(	with_transaction_cb const &	fn,
		v1::transaction_options const &	opts )

Start and commit a new standalone transaction using fn.

The behavior is approximately equivalent to:

this->start_transaction(opts);
while (/* unspecified *‍/) {
    try {
        fn();
        this->commit_transaction(); // Success.
    } catch (/* unspecified *‍/) {
       if (/* unspecified *‍/) {
           continue; // Retry attempt.
       } else {
           this->abort_transaction();
           throw; // Failure.
       }
    }
}

Any user-defined exceptions thrown by fn will be caught and rethrown after the standalone transaction has been aborted.

Warning

fn MUST allow any mongocxx::v1::server_error exceptions thrown by an operation within fn to propagate out of fn for correct retry attempt behavior. fn MUST NOT attempt to manually retry operations.

Note

This operation uses an internal, non-configurable time limit of 120 seconds. The transaction may be retried until this time limit is exceeded.

Exceptions

mongocxx::v1::exception	when a client-side error is encountered.
mongocxx::v1::server_error	when a server-side error is encountered and all retry attempts have failed.

---

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

• mongocxx/v1/client_session.hpp