1MONGOC_CLIENT_SESSION_T(3)         libmongoc        MONGOC_CLIENT_SESSION_T(3)
2
3
4

NAME

6       mongoc_client_session_t - mongoc_client_session_t
7
8       Use a session for a sequence of operations, optionally with causal con‐
9       sistency. See the MongoDB Manual Entry for Causal Consistency.
10

SYNOPSIS

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
19       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
25       Unacknowledged writes are prohibited with sessions.
26
27       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

EXAMPLE

34       example-session.c
35
36          /* gcc example-session.c -o example-session \
37           *     $(pkg-config --cflags --libs libmongoc-1.0) */
38
39          /* ./example-session [CONNECTION_STRING] */
40
41          #include <stdio.h>
42          #include <mongoc/mongoc.h>
43
44
45          int
46          main (int argc, char *argv[])
47          {
48             int exit_code = EXIT_FAILURE;
49
50             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
66             mongoc_init ();
67
68             if (argc > 1) {
69                uri_string = argv[1];
70             }
71
72             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
82             client = mongoc_client_new_from_uri (uri);
83             if (!client) {
84                goto done;
85             }
86
87             mongoc_client_set_error_api (client, 2);
88
89             /* 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
96             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
105             r = mongoc_collection_update_one (
106                collection, selector, update, update_opts, NULL /* reply */, &error);
107
108             if (!r) {
109                fprintf (stderr, "Update failed: %s\n", error.message);
110                goto done;
111             }
112
113             bson_destroy (selector);
114             selector = BCON_NEW ("_id", BCON_INT32 (1));
115             secondary = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
116
117             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
123             /* 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
131             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
137             if (mongoc_cursor_error (cursor, &error)) {
138                fprintf (stderr, "Cursor Failure: %s\n", error.message);
139                goto done;
140             }
141
142             exit_code = EXIT_SUCCESS;
143
144          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
177             mongoc_cleanup ();
178
179             return exit_code;
180          }
181
182

AUTHOR

184       MongoDB, Inc
185
187       2017-present, MongoDB, Inc
188
189
190
191
1921.23.1                           Oct 20, 2022       MONGOC_CLIENT_SESSION_T(3)
Impressum