.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "MONGOC_CLIENT_SESSION_WITH_TRANSACTION" "3" "Feb 25, 2024" "1.26.0" "libmongoc" .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .EX bool mongoc_client_session_with_transaction (mongoc_client_session_t *session, mongoc_client_session_with_transaction_cb_t cb, const mongoc_transaction_opt_t *opts, void *ctx, bson_t *reply, bson_error_t *error); .EE .UNINDENT .UNINDENT .sp This method will start a new transaction on \fBsession\fP, run \fBcb\fP, and then commit the transaction. If it cannot commit the transaction, the entire sequence may be retried, and \fBcb\fP may be run multiple times. \fBctx\fP will be passed to \fBcb\fP each time it is called. .sp This method has an internal time limit of 120 seconds, and will retry until that time limit is reached. This timeout is not configurable. .sp \fBcb\fP should not attempt to start new transactions, but should simply run operations meant to be contained within a transaction. The \fBcb\fP does not need to commit transactions; this is handled by the \fI\%mongoc_client_session_with_transaction()\fP\&. If \fBcb\fP does commit or abort a transaction, however, this method will return without taking further action. .sp The parameter \fBreply\fP is initialized even upon failure to simplify memory management. .SH PARAMETERS .INDENT 0.0 .IP \(bu 2 \fBsession\fP: A \fI\%mongoc_client_session_t\fP\&. .IP \(bu 2 \fBcb\fP: A \fI\%mongoc_client_session_with_transaction_cb_t\fP callback, which will run inside of a new transaction on the session. See example below. .IP \(bu 2 \fBopts\fP: An optional \fI\%mongoc_transaction_opt_t\fP\&. .IP \(bu 2 \fBctx\fP: A \fBvoid*\fP\&. This user\-provided data will be passed to \fBcb\fP\&. .IP \(bu 2 \fBreply\fP: A maybe\-\fBNULL\fP pointer to \fI\%overwritable storage\fP for a \fI\%bson_t\fP to contain the results. .IP \(bu 2 \fBerror\fP: An optional location for a \fI\%bson_error_t\fP or \fBNULL\fP\&. .UNINDENT .SH RETURN .sp Returns \fBtrue\fP if the transaction was completed successfully. Otherwise, returns \fBfalse\fP in case of failure. In cases of failure \fBerror\fP will also be set, except if the passed\-in \fBcb\fP fails without setting \fBerror\fP\&. If a non\-NULL \fBreply\fP is passed in, \fBreply\fP will be set to the value of the last server response, except if the passed\-in \fBcb\fP fails without setting a \fBreply\fP\&. .SH EXAMPLE .sp Use with_transaction() to run a callback within a transaction .INDENT 0.0 .INDENT 3.5 .sp .EX /* gcc example\-with\-transaction\-cb.c \-o example\-with\-transaction\-cb $(pkg\-config * \-\-cflags \-\-libs libmongoc\-1.0) */ /* ./example\-with\-transaction\-cb [CONNECTION_STRING] */ #include #include #include /* * We pass this context object to mongoc_client_session_with_transaction() along * with our callback function. The context object will be passed to our callback * function when it runs, so we can access it. */ typedef struct { mongoc_collection_t *collection; bson_t *insert_opts; } ctx_t; /* * We pass this method as the callback to * mongoc_client_session_with_transaction(). The insert that this method * performs will happen inside of a new transaction. */ bool create_and_insert_doc (mongoc_client_session_t *session, void *ctx, bson_t **reply, /* out param for our server reply */ bson_error_t *error) { /* * mongoc_collection_insert_one requires an uninitialized, stack\-allocated * bson_t to receive the update result */ bson_t local_reply; bson_t *doc = NULL; ctx_t *data = NULL; bool retval; /* * Create a new bson document \- { id: 1 } */ doc = BCON_NEW (\(dq_id\(dq, BCON_INT32 (1)); printf ( \(dqRunning the user\-defined callback in a newly created transaction...\en\(dq); data = (ctx_t *) ctx; retval = mongoc_collection_insert_one ( data\->collection, doc, data\->insert_opts, &local_reply, error); /* * To return to the mongoc_client_session_with_transaction() method, set * *reply to a new copy of our local_reply before destroying it. */ *reply = bson_copy (&local_reply); bson_destroy (&local_reply); bson_destroy (doc); return retval; } int main (int argc, char *argv[]) { int exit_code = EXIT_FAILURE; mongoc_uri_t *uri = NULL; const char *uri_string = \(dqmongodb://127.0.0.1/?appname=with\-txn\-cb\-example\(dq; mongoc_client_t *client = NULL; mongoc_database_t *database = NULL; mongoc_collection_t *collection = NULL; mongoc_client_session_t *session = NULL; bson_t *insert_opts = NULL; bson_t reply; ctx_t ctx; char *str; bson_error_t error; /* * Required to initialize libmongoc\(aqs internals */ mongoc_init (); /* * Optionally get MongoDB URI from command line */ if (argc > 1) { uri_string = argv[1]; } /* * Safely create a MongoDB URI object from the given string */ uri = mongoc_uri_new_with_error (uri_string, &error); if (!uri) { MONGOC_ERROR (\(dqfailed to parse URI: %s\en\(dq \(dqerror message: %s\en\(dq, uri_string, error.message); goto done; } /* * Create a new client instance */ client = mongoc_client_new_from_uri (uri); if (!client) { goto done; } mongoc_client_set_error_api (client, 2); /* * Get a handle on the database \(dqexample\-with\-txn\-cb\(dq */ database = mongoc_client_get_database (client, \(dqexample\-with\-txn\-cb\(dq); /* * Inserting into a nonexistent collection normally creates it, but a * collection can\(aqt be created in a transaction; create it now */ collection = mongoc_database_create_collection (database, \(dqcollection\(dq, NULL, &error); if (!collection) { /* code 48 is NamespaceExists, see error_codes.err in mongodb source */ if (error.code == 48) { collection = mongoc_database_get_collection (database, \(dqcollection\(dq); } else { MONGOC_ERROR (\(dqFailed to create collection: %s\(dq, error.message); goto done; } } /* * Pass NULL for options \- by default the session is causally consistent */ session = mongoc_client_start_session (client, NULL, &error); if (!session) { MONGOC_ERROR (\(dqFailed to start session: %s\(dq, error.message); goto done; } /* * Append a logical session id to command options */ insert_opts = bson_new (); if (!mongoc_client_session_append (session, insert_opts, &error)) { MONGOC_ERROR (\(dqCould not add session to opts: %s\(dq, error.message); goto done; } ctx.collection = collection; ctx.insert_opts = insert_opts; /* * This method will start a new transaction on session, run our callback * function, i.e., &create_and_insert_doc, passing &ctx as an argument and * commit the transaction. */ if (!mongoc_client_session_with_transaction ( session, &create_and_insert_doc, NULL, &ctx, &reply, &error)) { MONGOC_ERROR (\(dqInsert failed: %s\(dq, error.message); goto done; } str = bson_as_json (&reply, NULL); printf (\(dq%s\en\(dq, str); exit_code = EXIT_SUCCESS; done: bson_free (str); bson_destroy (&reply); bson_destroy (insert_opts); mongoc_client_session_destroy (session); mongoc_collection_destroy (collection); mongoc_database_destroy (database); mongoc_client_destroy (client); mongoc_uri_destroy (uri); mongoc_cleanup (); return exit_code; } .EE .UNINDENT .UNINDENT .SH AUTHOR MongoDB, Inc .SH COPYRIGHT 2017-present, MongoDB, Inc .\" Generated by docutils manpage writer. .