Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
MONGOC_CLIENT_SESSION_T(3)	   libmongoc	    MONGOC_CLIENT_SESSION_T(3)

Use  a	session	 for  a	sequence of operations,	optionally with	causal consis-
tency. See the MongoDB Manual Entry for	Causal Consistency.

SYNOPSIS
       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 consis-
       tency, 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 ses-
       sion  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.

FORK SAFETY
       A  mongoc_client_session_t is only usable in the	parent process after a
       fork. The child process must call mongoc_client_reset() on  the	client
       field.

EXAMPLE
       example-session.c

	  /* gcc example-session.c -o example-session \
	   *	 $(pkg-config --cflags --libs libmongoc-1.0) */

	  /* ./example-session [CONNECTION_STRING] */

	  #include <stdio.h>
	  #include <mongoc/mongoc.h>

	  int
	  main (int argc, char *argv[])
	  {
	     int exit_code = EXIT_FAILURE;

	     mongoc_client_t *client = NULL;
	     const char	*uri_string = "mongodb://127.0.0.1/?appname=session-example";
	     mongoc_uri_t *uri = NULL;
	     mongoc_client_session_t *client_session = NULL;
	     mongoc_collection_t *collection = NULL;
	     bson_error_t error;
	     bson_t *selector =	NULL;
	     bson_t *update = NULL;
	     bson_t *update_opts = NULL;
	     bson_t *find_opts = NULL;
	     mongoc_read_prefs_t *secondary = NULL;
	     mongoc_cursor_t *cursor = NULL;
	     const bson_t *doc;
	     char *str;
	     bool r;

	     mongoc_init ();

	     if	(argc >	1) {
		uri_string = argv[1];
	     }

	     uri = mongoc_uri_new_with_error (uri_string, &error);
	     if	(!uri) {
		fprintf	(stderr,
			 "failed to parse URI: %s\n"
			 "error	message:       %s\n",
			 uri_string,
			 error.message);
		goto done;
	     }

	     client = mongoc_client_new_from_uri (uri);
	     if	(!client) {
		goto done;
	     }

	     mongoc_client_set_error_api (client, 2);

	     /*	pass NULL for options -	by default the session is causally consistent */
	     client_session = mongoc_client_start_session (client, NULL, &error);
	     if	(!client_session) {
		fprintf	(stderr, "Failed to start session: %s\n", error.message);
		goto done;
	     }

	     collection	= mongoc_client_get_collection (client,	"test",	"collection");
	     selector =	BCON_NEW ("_id", BCON_INT32 (1));
	     update = BCON_NEW ("$inc",	"{", "x", BCON_INT32 (1), "}");
	     update_opts = bson_new ();
	     if	(!mongoc_client_session_append (client_session,	update_opts, &error)) {
		fprintf	(stderr, "Could	not add	session	to opts: %s\n",	error.message);
		goto done;
	     }

	     r = mongoc_collection_update_one (collection, selector, update, update_opts, NULL /* reply	*/, &error);

	     if	(!r) {
		fprintf	(stderr, "Update failed: %s\n",	error.message);
		goto done;
	     }

	     bson_destroy (selector);
	     selector =	BCON_NEW ("_id", BCON_INT32 (1));
	     secondary = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);

	     find_opts = BCON_NEW ("maxTimeMS",	BCON_INT32 (2000));
	     if	(!mongoc_client_session_append (client_session,	find_opts, &error)) {
		fprintf	(stderr, "Could	not add	session	to opts: %s\n",	error.message);
		goto done;
	     }

	     /*	read from secondary. since we're in a causally consistent session, the
	      *	data is	guaranteed to reflect the update we did	on the primary.	the query
	      *	blocks waiting for the secondary to catch up, if necessary, or times out
	      *	and fails after	2000 ms.
	      */
	     cursor = mongoc_collection_find_with_opts (collection, selector, find_opts, secondary);

	     while (mongoc_cursor_next (cursor,	&doc)) {
		str = bson_as_relaxed_extended_json (doc, NULL);
		fprintf	(stdout, "%s\n", str);
		bson_free (str);
	     }

	     if	(mongoc_cursor_error (cursor, &error)) {
		fprintf	(stderr, "Cursor Failure: %s\n", error.message);
		goto done;
	     }

	     exit_code = EXIT_SUCCESS;

	  done:
	     if	(find_opts) {
		bson_destroy (find_opts);
	     }
	     if	(update) {
		bson_destroy (update);
	     }
	     if	(selector) {
		bson_destroy (selector);
	     }
	     if	(update_opts) {
		bson_destroy (update_opts);
	     }
	     if	(secondary) {
		mongoc_read_prefs_destroy (secondary);
	     }
	     /*	destroy	cursor,	collection, session before the client they came	from */
	     if	(cursor) {
		mongoc_cursor_destroy (cursor);
	     }
	     if	(collection) {
		mongoc_collection_destroy (collection);
	     }
	     if	(client_session) {
		mongoc_client_session_destroy (client_session);
	     }
	     if	(uri) {
		mongoc_uri_destroy (uri);
	     }
	     if	(client) {
		mongoc_client_destroy (client);
	     }

	     mongoc_cleanup ();

	     return exit_code;
	  }

AUTHOR
       MongoDB,	Inc

COPYRIGHT
       2009-present, MongoDB, Inc.

1.30.2				 Apr 12, 2025	    MONGOC_CLIENT_SESSION_T(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mongoc_client_session_t&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help