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 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
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 mongoc_session_opts_set_causal_con‐
22       sistency(), then free the struct with mongoc_session_opts_destroy.
23
24       Unacknowledged writes are prohibited with sessions.
25
26       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

EXAMPLE

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

AUTHOR

183       MongoDB, Inc
184
186       2017-present, MongoDB, Inc
187
188
189
190
1911.20.0                           Nov 18, 2021       MONGOC_CLIENT_SESSION_T(3)
Impressum