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 a
13 sequence of operations and multi-document transactions, then free it
14 with mongoc_client_session_destroy(). Any mongoc_cursor_t or mon‐
15 goc_change_stream_t using a session must be destroyed before the ses‐
16 sion, 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 mongoc_session_opts_set_causal_con‐
22 sistency(), then free the struct with mongoc_session_opts_destroy.
23 Unacknowledged writes are prohibited with sessions.
25 A mongoc_client_session_t must be used by only one thread at a time.
27 Due to session pooling, mongoc_client_start_session may return a ses‐
28 sion that has been idle for some time and is about to be closed after
29 its idle timeout. Use the session within one minute of acquiring it to
30 refresh the session and avoid a timeout.
31
33 example-session.c
34 /* gcc example-session.c -o example-session \
36 * $(pkg-config --cflags --libs libmongoc-1.0) */
37 /* ./example-session [CONNECTION_STRING] */
39 #include <stdio.h>
41 #include <mongoc/mongoc.h>
42 int
45 main (int argc, char *argv[])
46 {
47 int exit_code = EXIT_FAILURE;
48 mongoc_client_t *client = NULL;
50 const char *uri_string = "mongodb://127.0.0.1/?appname=session-example";
51 mongoc_uri_t *uri = NULL;
52 mongoc_client_session_t *client_session = NULL;
53 mongoc_collection_t *collection = NULL;
54 bson_error_t error;
55 bson_t *selector = NULL;
56 bson_t *update = NULL;
57 bson_t *update_opts = NULL;
58 bson_t *find_opts = NULL;
59 mongoc_read_prefs_t *secondary = NULL;
60 mongoc_cursor_t *cursor = NULL;
61 const bson_t *doc;
62 char *str;
63 bool r;
64 mongoc_init ();
66 if (argc > 1) {
68 uri_string = argv[1];
69 }
70 uri = mongoc_uri_new_with_error (uri_string, &error);
72 if (!uri) {
73 fprintf (stderr,
74 "failed to parse URI: %s\n"
75 "error message: %s\n",
76 uri_string,
77 error.message);
78 goto done;
79 }
80 client = mongoc_client_new_from_uri (uri);
82 if (!client) {
83 goto done;
84 }
85 mongoc_client_set_error_api (client, 2);
87 /* pass NULL for options - by default the session is causally consistent */
89 client_session = mongoc_client_start_session (client, NULL, &error);
90 if (!client_session) {
91 fprintf (stderr, "Failed to start session: %s\n", error.message);
92 goto done;
93 }
94 collection = mongoc_client_get_collection (client, "test", "collection");
96 selector = BCON_NEW ("_id", BCON_INT32 (1));
97 update = BCON_NEW ("$inc", "{", "x", BCON_INT32 (1), "}");
98 update_opts = bson_new ();
99 if (!mongoc_client_session_append (client_session, update_opts, &error)) {
100 fprintf (stderr, "Could not add session to opts: %s\n", error.message);
101 goto done;
102 }
103 r = mongoc_collection_update_one (
105 collection, selector, update, update_opts, NULL /* reply */, &error);
106 if (!r) {
108 fprintf (stderr, "Update failed: %s\n", error.message);
109 goto done;
110 }
111 bson_destroy (selector);
113 selector = BCON_NEW ("_id", BCON_INT32 (1));
114 secondary = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
115 find_opts = BCON_NEW ("maxTimeMS", BCON_INT32 (2000));
117 if (!mongoc_client_session_append (client_session, find_opts, &error)) {
118 fprintf (stderr, "Could not add session to opts: %s\n", error.message);
119 goto done;
120 };
121 /* read from secondary. since we're in a causally consistent session, the
123 * data is guaranteed to reflect the update we did on the primary. the query
124 * blocks waiting for the secondary to catch up, if necessary, or times out
125 * and fails after 2000 ms.
126 */
127 cursor = mongoc_collection_find_with_opts (
128 collection, selector, find_opts, secondary);
129 while (mongoc_cursor_next (cursor, &doc)) {
131 str = bson_as_json (doc, NULL);
132 fprintf (stdout, "%s\n", str);
133 bson_free (str);
134 }
135 if (mongoc_cursor_error (cursor, &error)) {
137 fprintf (stderr, "Cursor Failure: %s\n", error.message);
138 goto done;
139 }
140 exit_code = EXIT_SUCCESS;
142 done:
144 if (find_opts) {
145 bson_destroy (find_opts);
146 }
147 if (update) {
148 bson_destroy (update);
149 }
150 if (selector) {
151 bson_destroy (selector);
152 }
153 if (update_opts) {
154 bson_destroy (update_opts);
155 }
156 if (secondary) {
157 mongoc_read_prefs_destroy (secondary);
158 }
159 /* destroy cursor, collection, session before the client they came from */
160 if (cursor) {
161 mongoc_cursor_destroy (cursor);
162 }
163 if (collection) {
164 mongoc_collection_destroy (collection);
165 }
166 if (client_session) {
167 mongoc_client_session_destroy (client_session);
168 }
169 if (uri) {
170 mongoc_uri_destroy (uri);
171 }
172 if (client) {
173 mongoc_client_destroy (client);
174 }
175 mongoc_cleanup ();
177 return exit_code;
179 }
180
183 MongoDB, Inc
184
186 2017-present, MongoDB, Inc
1871.20.0 Nov 18, 2021 MONGOC_CLIENT_SESSION_T(3)