1MONGOC_CLIENT_SESSION_T(3) libmongoc MONGOC_CLIENT_SESSION_T(3)
2
6 mongoc_client_session_t - mongoc_client_session_t
7 Use a session for a sequence of operations, optionally with causal con‐
9 sistency. See the MongoDB Manual Entry for Causal Consistency.
10
12 Start a session with mongoc_client_start_session(), use the session for
13 a sequence of operations and multi-document transactions, then free it
14 with mongoc_client_session_destroy(). Any mongoc_cursor_t or
15 mongoc_change_stream_t using a session must be destroyed before the
16 session, and a session must be destroyed before the mongoc_client_t it
17 came from.
18 By default, sessions are causally consistent. To disable causal consis‐
20 tency, before starting a session create a mongoc_session_opt_t with
21 mongoc_session_opts_new() and call
22 mongoc_session_opts_set_causal_consistency(), then free the struct with
23 mongoc_session_opts_destroy().
24 Unacknowledged writes are prohibited with sessions.
26 A mongoc_client_session_t must be used by only one thread at a time.
28 Due to session pooling, mongoc_client_start_session() may return a ses‐
29 sion that has been idle for some time and is about to be closed after
30 its idle timeout. Use the session within one minute of acquiring it to
31 refresh the session and avoid a timeout.
32
34 example-session.c
35 /* gcc example-session.c -o example-session \
37 * $(pkg-config --cflags --libs libmongoc-1.0) */
38 /* ./example-session [CONNECTION_STRING] */
40 #include <stdio.h>
42 #include <mongoc/mongoc.h>
43 int
46 main (int argc, char *argv[])
47 {
48 int exit_code = EXIT_FAILURE;
49 mongoc_client_t *client = NULL;
51 const char *uri_string = "mongodb://127.0.0.1/?appname=session-example";
52 mongoc_uri_t *uri = NULL;
53 mongoc_client_session_t *client_session = NULL;
54 mongoc_collection_t *collection = NULL;
55 bson_error_t error;
56 bson_t *selector = NULL;
57 bson_t *update = NULL;
58 bson_t *update_opts = NULL;
59 bson_t *find_opts = NULL;
60 mongoc_read_prefs_t *secondary = NULL;
61 mongoc_cursor_t *cursor = NULL;
62 const bson_t *doc;
63 char *str;
64 bool r;
65 mongoc_init ();
67 if (argc > 1) {
69 uri_string = argv[1];
70 }
71 uri = mongoc_uri_new_with_error (uri_string, &error);
73 if (!uri) {
74 fprintf (stderr,
75 "failed to parse URI: %s\n"
76 "error message: %s\n",
77 uri_string,
78 error.message);
79 goto done;
80 }
81 client = mongoc_client_new_from_uri (uri);
83 if (!client) {
84 goto done;
85 }
86 mongoc_client_set_error_api (client, 2);
88 /* pass NULL for options - by default the session is causally consistent */
90 client_session = mongoc_client_start_session (client, NULL, &error);
91 if (!client_session) {
92 fprintf (stderr, "Failed to start session: %s\n", error.message);
93 goto done;
94 }
95 collection = mongoc_client_get_collection (client, "test", "collection");
97 selector = BCON_NEW ("_id", BCON_INT32 (1));
98 update = BCON_NEW ("$inc", "{", "x", BCON_INT32 (1), "}");
99 update_opts = bson_new ();
100 if (!mongoc_client_session_append (client_session, update_opts, &error)) {
101 fprintf (stderr, "Could not add session to opts: %s\n", error.message);
102 goto done;
103 }
104 r = mongoc_collection_update_one (
106 collection, selector, update, update_opts, NULL /* reply */, &error);
107 if (!r) {
109 fprintf (stderr, "Update failed: %s\n", error.message);
110 goto done;
111 }
112 bson_destroy (selector);
114 selector = BCON_NEW ("_id", BCON_INT32 (1));
115 secondary = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
116 find_opts = BCON_NEW ("maxTimeMS", BCON_INT32 (2000));
118 if (!mongoc_client_session_append (client_session, find_opts, &error)) {
119 fprintf (stderr, "Could not add session to opts: %s\n", error.message);
120 goto done;
121 };
122 /* read from secondary. since we're in a causally consistent session, the
124 * data is guaranteed to reflect the update we did on the primary. the query
125 * blocks waiting for the secondary to catch up, if necessary, or times out
126 * and fails after 2000 ms.
127 */
128 cursor = mongoc_collection_find_with_opts (
129 collection, selector, find_opts, secondary);
130 while (mongoc_cursor_next (cursor, &doc)) {
132 str = bson_as_json (doc, NULL);
133 fprintf (stdout, "%s\n", str);
134 bson_free (str);
135 }
136 if (mongoc_cursor_error (cursor, &error)) {
138 fprintf (stderr, "Cursor Failure: %s\n", error.message);
139 goto done;
140 }
141 exit_code = EXIT_SUCCESS;
143 done:
145 if (find_opts) {
146 bson_destroy (find_opts);
147 }
148 if (update) {
149 bson_destroy (update);
150 }
151 if (selector) {
152 bson_destroy (selector);
153 }
154 if (update_opts) {
155 bson_destroy (update_opts);
156 }
157 if (secondary) {
158 mongoc_read_prefs_destroy (secondary);
159 }
160 /* destroy cursor, collection, session before the client they came from */
161 if (cursor) {
162 mongoc_cursor_destroy (cursor);
163 }
164 if (collection) {
165 mongoc_collection_destroy (collection);
166 }
167 if (client_session) {
168 mongoc_client_session_destroy (client_session);
169 }
170 if (uri) {
171 mongoc_uri_destroy (uri);
172 }
173 if (client) {
174 mongoc_client_destroy (client);
175 }
176 mongoc_cleanup ();
178 return exit_code;
180 }
181
184 MongoDB, Inc
185
187 2017-present, MongoDB, Inc
1881.24.3 Aug 17, 2023 MONGOC_CLIENT_SESSION_T(3)