Loading...
Searching...
No Matches
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)

## 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.

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 *&zwj;/) {
try {
fn();
this->commit_transaction(); // Success.
} catch (/* unspecified *&zwj;/) {
if (/* unspecified *&zwj;/) {
continue; // Retry attempt.
} else {
this->abort_transaction();
throw; // Failure.
}
}
}
mongocxx::v1::client_session::start_transaction
void start_transaction()
Start a new transaction.
mongocxx::v1::client_session::opts
options opts() const
Return the options used to create this client session.

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