mongoc_client_start_session()

Synopsis

mongoc_client_session_t *
mongoc_client_start_session (mongoc_client_t *client,
                             mongoc_session_opt_t *opts,
                             bson_error_t *error)

Create a session for a sequence of operations.

Start a session with mongoc_client_start_session(), use the session for a sequence of operations, then free it with mongoc_client_session_destroy(). A session must be freed before the mongoc_client_t it came from.

By default, sessions are causally consistent. To disable causal consistency, before starting a session create a mongoc_session_opt_t with mongoc_session_opts_new() and call mongoc_session_opts_set_causal_consistency(), then free the struct with mongoc_session_opts_destroy().

Unacknowledged writes are not causally consistent. If you execute a write operation with a mongoc_write_concern_t on which you have called mongoc_write_concern_set_w() with a value of 0, the write does not participate in causal consistency.

A mongoc_client_session_t must be used by only one thread at a time. Due to session pooling, mongoc_client_start_session() may return a session that has been idle for some time and is about to be closed after its idle timeout. Use the session within one minute of acquiring it to refresh the session and avoid a timeout.

Parameters

Returns

If successful, this function returns a newly allocated mongoc_client_session_t that should be freed with mongoc_client_session_destroy() when no longer in use. On error, returns NULL and sets error.