plucky (3) mongoc_client_start_session.3.gz

Provided by: libmongoc-doc_1.30.0-1_all bug

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 and
       multi-document transactions, then free it with mongoc_client_session_destroy().  Any  mongoc_cursor_t  or
       mongoc_change_stream_t  using  a  session  must  be  destroyed  before the session, and a session must be
       destroyed 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 prohibited with sessions.

       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
       • client: A mongoc_client_t.

       • opts: An optional mongoc_session_opt_t.

       • error: A bson_error_t.


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.


ERRORS
       This function can fail if the driver is not built with crypto support, if opts is  misconfigured,  or  if
       the session is configured with options that the server does not support.


AUTHOR
       MongoDB, Inc


       2009-present, MongoDB, Inc.