CDRIVER-2558 transactions documentation

Author: ajdavis

.gitignore

@@ -37,6 +37,7 @@ example-gridfs
 example-matcher
 example-session
 example-sdam-monitoring
+example-transaction
 example-update
 filter-bsondump
 find-and-modify

src/libmongoc/CMakeLists.txt

@@ -803,6 +803,7 @@ mongoc_add_example (example-command-with-opts TRUE ${PROJECT_SOURCE_DIR}/example
 mongoc_add_example (example-create-indexes TRUE ${PROJECT_SOURCE_DIR}/examples/example-create-indexes.c)
 mongoc_add_example (example-scram TRUE ${PROJECT_SOURCE_DIR}/examples/example-scram.c)
 mongoc_add_example (example-session TRUE ${PROJECT_SOURCE_DIR}/examples/example-session.c)
+mongoc_add_example (example-transaction TRUE ${PROJECT_SOURCE_DIR}/examples/example-transaction.c)
 mongoc_add_example (mongoc-dump TRUE ${PROJECT_SOURCE_DIR}/examples/mongoc-dump.c)
 mongoc_add_example (mongoc-ping TRUE ${PROJECT_SOURCE_DIR}/examples/mongoc-ping.c)
 mongoc_add_example (mongoc-tail TRUE ${PROJECT_SOURCE_DIR}/examples/mongoc-tail.c)

src/libmongoc/doc/includes/opts-sources.txt

@@ -0,0 +1,11 @@
+Read preferences, read and write concern, and collation can be overridden by various sources. The highest-priority sources for these options are listed first:
+
+================== ============== ============== =========
+Read Preferences   Read Concern   Write Concern  Collation
+================== ============== ============== =========
+``read_prefs``     ``opts``       ``opts``       ``opts``
+Transaction        Transaction    Transaction
+|opts-source|
+================== ============== ============== =========
+
+:ref:`See the example for transactions <mongoc_client_session_start_transaction_example>` and for :ref:`the "distinct" command with opts <mongoc_client_read_command_with_opts_example>`.

src/libmongoc/doc/includes/read-cmd-opts-sources.txt

@@ -0,0 +1,3 @@
+Use this function for commands that read such as "count" or "distinct".
+
+.. include:: includes/read-opts-sources.txt

src/libmongoc/doc/includes/read-opts-sources.txt

@@ -0,0 +1,11 @@
+Read preferences, read concern, and collation can be overridden by various sources. The highest-priority sources for these options are listed first in the following table. No write concern is applied.
+
+================== ============== =========
+Read Preferences   Read Concern   Collation
+================== ============== =========
+``read_prefs``     ``opts``       ``opts``
+Transaction        Transaction
+|opts-source|
+================== ============== =========
+
+:ref:`See the example for transactions <mongoc_client_session_start_transaction_example>` and for :ref:`the "distinct" command with opts <mongoc_client_read_command_with_opts_example>`.

src/libmongoc/doc/includes/read-opts.txt

@@ -1,6 +1,6 @@
 ``opts`` may be NULL or a BSON document with additional command options:
 
 * ``readConcern``: Construct a :symbol:`mongoc_read_concern_t` and use :symbol:`mongoc_read_concern_append` to add the read concern to ``opts``. See the example code for :symbol:`mongoc_client_read_command_with_opts`. Read concern requires MongoDB 3.2 or later, otherwise an error is returned.
-* ``sessionId``: Construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session` and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
+* ``sessionId``: First, construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session`. You can begin a transaction with :symbol:`mongoc_client_session_start_transaction`, optionally with a :symbol:`mongoc_transaction_opt_t` that overrides the options inherited from |opts-source|, and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
 * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order <setting_collation_order>`, and `the MongoDB Manual entry on Collation <https://docs.mongodb.com/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :symbol:`mongoc_client_select_server`, then :symbol:`mongoc_server_description_id` on its return value.

src/libmongoc/doc/includes/read-write-opts-sources.txt

@@ -0,0 +1,13 @@
+Use this function for commands that both read and write, such as "mapReduce" with an output collection.
+
+Read and write concern and collation can be overridden by various sources. The highest-priority sources for these options are listed first in the following table. Read preferences are *not* applied. The write concern is omitted for MongoDB before 3.4.
+
+============== ============== =========
+Read Concern   Write Concern  Collation
+============== ============== =========
+``opts``       ``opts``       ``opts``
+Transaction    Transaction
+|opts-source|  |opts-source|
+============== ============== =========
+
+:ref:`See the example for transactions <mongoc_client_session_start_transaction_example>` and for :ref:`the "distinct" command with opts <mongoc_client_read_command_with_opts_example>`.

src/libmongoc/doc/includes/read-write-opts.txt

@@ -2,6 +2,6 @@
 
 * ``readConcern``: Construct a :symbol:`mongoc_read_concern_t` and use :symbol:`mongoc_read_concern_append` to add the read concern to ``opts``. See the example code for :symbol:`mongoc_client_read_command_with_opts`. Read concern requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``writeConcern``: Construct a :symbol:`mongoc_write_concern_t` and use :symbol:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :symbol:`mongoc_client_write_command_with_opts`.
-* ``sessionId``: Construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session` and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
+* ``sessionId``: First, construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session`. You can begin a transaction with :symbol:`mongoc_client_session_start_transaction`, optionally with a :symbol:`mongoc_transaction_opt_t` that overrides the options inherited from |opts-source|, and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
 * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order <setting_collation_order>`, and `the MongoDB Manual entry on Collation <https://docs.mongodb.com/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :symbol:`mongoc_client_select_server`, then :symbol:`mongoc_server_description_id` on its return value.

src/libmongoc/doc/includes/write-opts-sources.txt

@@ -0,0 +1,11 @@
+Use this function for commands that write such as "drop" or "createRole" (but not for "insert", "update", or "delete", see `Basic Write Operations`_). Write concern and collation can be overridden by various sources. The highest-priority sources for these options are listed first in the following table. The write concern is omitted for MongoDB before 3.4.
+
+============== =========
+Write Concern  Collation
+============== =========
+``opts``       ``opts``
+Transaction
+|opts-source|
+============== =========
+
+:ref:`See the example for transactions <mongoc_client_session_start_transaction_example>` and for :ref:`the "distinct" command with opts <mongoc_client_read_command_with_opts_example>`.

src/libmongoc/doc/includes/write-opts.txt

@@ -1,6 +1,6 @@
 ``opts`` may be NULL or a BSON document with additional command options:
 
 * ``writeConcern``: Construct a :symbol:`mongoc_write_concern_t` and use :symbol:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :symbol:`mongoc_client_write_command_with_opts`.
-* ``sessionId``: Construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session` and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
+* ``sessionId``: First, construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session`. You can begin a transaction with :symbol:`mongoc_client_session_start_transaction`, optionally with a :symbol:`mongoc_transaction_opt_t` that overrides the options inherited from |opts-source|, and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
 * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order <setting_collation_order>`, and `the MongoDB Manual entry on Collation <https://docs.mongodb.com/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :symbol:`mongoc_client_select_server`, then :symbol:`mongoc_server_description_id` on its return value.

src/libmongoc/doc/mongoc_client_command_with_opts.rst

@@ -20,7 +20,9 @@ Synopsis
 
 Execute a command on the server, interpreting ``opts`` according to the MongoDB server version. To send a raw command to the server without any of this logic, use :symbol:`mongoc_client_command_simple`.
 
-Read preferences are applied from ``read_prefs`` or else from ``client``. Collation, read concern, and write concern are applied from ``opts`` (:ref:`see example for the "distinct" command with opts <mongoc_client_read_command_with_opts_example>`). The write concern is ignored for MongoDB before 3.4.
+.. |opts-source| replace:: ``client``
+
+.. include:: includes/opts-sources.txt
 
 ``reply`` is always initialized, and must be freed with :symbol:`bson:bson_destroy()`.
 

src/libmongoc/doc/mongoc_client_read_command_with_opts.rst

@@ -19,7 +19,9 @@ Synopsis
 
 Execute a command on the server, applying logic that is specific to commands that read, and taking the MongoDB server version into account. To send a raw command to the server without any of this logic, use :symbol:`mongoc_client_command_simple`.
 
-Use this function for commands that read such as "count" or "distinct". Read concern is applied from ``opts`` or else from ``client``. Collation is applied from ``opts`` (see example below). Read preferences are applied from ``read_prefs`` or else from ``client``. No write concern is applied.
+.. |opts-source| replace:: ``client``
+
+.. include:: includes/read-cmd-opts-sources.txt
 
 ``reply`` is always initialized, and must be freed with :symbol:`bson:bson_destroy()`.
 

src/libmongoc/doc/mongoc_client_read_write_command_with_opts.rst

@@ -20,9 +20,9 @@ Synopsis
 
 Execute a command on the server, applying logic for commands that both read and write, and taking the MongoDB server version into account. To send a raw command to the server without any of this logic, use :symbol:`mongoc_client_command_simple`.
 
-Use this function for commands that both read and write, such as "mapReduce" with an output collection.
+.. |opts-source| replace:: ``client``
 
-Read concern is applied from ``opts`` or else from ``client``. Collation is applied from ``opts`` (:ref:`see example for the "distinct" command with opts <mongoc_client_read_command_with_opts_example>`). Read preferences are *not* applied. Write concern is applied from ``opts``, or else from ``client``. The write concern is omitted for MongoDB before 3.4.
+.. include:: includes/read-write-opts-sources.txt
 
 ``reply`` is always initialized, and must be freed with :symbol:`bson:bson_destroy()`.
 

src/libmongoc/doc/mongoc_client_session_start_transaction.rst

@@ -30,6 +30,15 @@ Return
 
 Returns true if the transaction was started. Returns ``false`` and sets ``error`` if there are invalid arguments, such as a session with a transaction already in progress.
 
+.. _mongoc_client_session_start_transaction_example:
+
+Example
+-------
+
+.. literalinclude:: ../examples/example-transaction.c
+   :language: c
+   :caption: example-transaction.c
+
 .. only:: html
 
   .. taglist:: See Also:

src/libmongoc/doc/mongoc_client_write_command_with_opts.rst

@@ -18,7 +18,9 @@ Synopsis
 
 Execute a command on the server, applying logic that is specific to commands that write, and taking the MongoDB server version into account. To send a raw command to the server without any of this logic, use :symbol:`mongoc_client_command_simple`.
 
-Use this function for commands that write such as "drop" or "createRole" (but not for "insert", "update", or "delete", see `Basic Write Operations`_). Write concern is applied from ``opts``, or else from ``client``. The write concern is omitted for MongoDB before 3.4. Collation is applied from ``opts`` (:ref:`see example for the "distinct" command with opts <mongoc_client_read_command_with_opts_example>`). No read concern or read preferences are applied.
+.. |opts-source| replace:: ``client``
+
+.. include:: includes/write-opts-sources.txt
 
 ``reply`` is always initialized, and must be freed with :symbol:`bson:bson_destroy()`.
 

src/libmongoc/doc/mongoc_collection_aggregate.rst

@@ -21,7 +21,7 @@ Parameters
 
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``flags``: A :symbol:`mongoc_query_flags_t`.
-* ``pipeline``: A :symbol:`bson:bson_t` containing the pipeline array.
+* ``pipeline``: A :symbol:`bson:bson_t`, either a BSON array or a BSON document containing an array field named "pipeline".
 * ``opts``: A :symbol:`bson:bson_t` containing options for the command, or ``NULL``.
 * ``read_prefs``: A :symbol:`mongoc_read_prefs_t` or ``NULL``.
 
@@ -40,15 +40,19 @@ For a list of all options, see `the MongoDB Manual entry on the aggregate comman
 Description
 -----------
 
-This function shall execute an aggregation query on the underlying 'collection'. The bson 'pipeline' is not validated, simply passed along as appropriate to the server.  As such, compatibility and errors should be validated in the appropriate server documentation.
+This function shall execute an aggregation query on the underlying collection. For more information on building aggregation pipelines, see `the MongoDB Manual entry on the aggregate command <http://docs.mongodb.org/manual/reference/command/aggregate/>`_.
 
-For more information on building MongoDB pipelines, see `the MongoDB Manual entry on the aggregate command <http://docs.mongodb.org/manual/reference/command/aggregate/>`_.
+Read preferences, read and write concern, and collation can be overridden by various sources. The highest-priority sources for these options are listed first in the following table. Write concern is applied from ``opts``, or if ``opts`` has no write concern and the aggregation pipeline includes "$out", the write concern is applied from ``collection``. The write concern is omitted for MongoDB before 3.4.
 
-.. note::
+================== ============== ============== =========
+Read Preferences   Read Concern   Write Concern  Collation
+================== ============== ============== =========
+``read_prefs``     ``opts``       ``opts``       ``opts``
+Transaction        Transaction    Transaction
+``collection``     ``collection`` ``collection``
+================== ============== ============== =========
 
-  The ``pipeline`` parameter should contain a field named ``pipeline`` containing a BSON array of pipeline stages.
-
-Read concern is applied from ``opts`` or else from ``collection``. Collation is applied from ``opts`` (:ref:`see example for the "distinct" command with opts <mongoc_client_read_command_with_opts_example>`). Read preferences are applied from ``read_prefs`` or else from ``collection``. Write concern is applied from ``opts``, or if ``opts`` has no write concern and the aggregation pipeline includes "$out", the write concern is applied from ``collection``. The write concern is omitted for MongoDB before 3.4.
+:ref:`See the example for transactions <mongoc_client_session_start_transaction_example>` and for :ref:`the "distinct" command with opts <mongoc_client_read_command_with_opts_example>`.
 
 Returns
 -------

src/libmongoc/doc/mongoc_collection_command_with_opts.rst

@@ -19,7 +19,9 @@ Synopsis
 
 Execute a command on the server, interpreting ``opts`` according to the MongoDB server version. To send a raw command to the server without any of this logic, use :symbol:`mongoc_client_command_simple`.
 
-Read preferences are applied from ``read_prefs`` or else from ``collection``. Collation, read concern, and write concern are applied from ``opts`` (:ref:`see example for the "distinct" command with opts <mongoc_client_read_command_with_opts_example>`). The write concern is ignored for MongoDB before 3.4.
+.. |opts-source| replace:: ``collection``
+
+.. include:: includes/opts-sources.txt
 
 ``reply`` is always initialized, and must be freed with :symbol:`bson:bson_destroy()`.
 

src/libmongoc/doc/mongoc_collection_count_with_opts.rst

@@ -30,6 +30,8 @@ Parameters
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`, otherwise uses the collection's read preference.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
+.. |opts-source| replace:: ``collection``
+
 .. include:: includes/read-opts.txt
 
 Description

src/libmongoc/doc/mongoc_collection_drop_index_with_opts.rst

@@ -21,6 +21,8 @@ Parameters
 * ``index_name``: A string containing the name of the index.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
+.. |opts-source| replace:: ``collection``
+
 .. include:: includes/write-opts.txt
 
 Description

src/libmongoc/doc/mongoc_collection_drop_with_opts.rst

@@ -19,6 +19,8 @@ Parameters
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
+.. |opts-source| replace:: ``collection``
+
 .. include:: includes/write-opts.txt
 
 Description

src/libmongoc/doc/mongoc_collection_find_with_opts.rst

@@ -30,6 +30,10 @@ Query on ``collection``, passing arbitrary query options to the server in ``opts
 
 To target a specific server, include an integer "serverId" field in ``opts`` with an id obtained first by calling :symbol:`mongoc_client_select_server`, then :symbol:`mongoc_server_description_id` on its return value.
 
+.. |opts-source| replace:: ``collection``
+
+.. include:: includes/read-opts-sources.txt
+
 Returns
 -------
 
@@ -117,18 +121,22 @@ Option                   BSON type           Option               BSON type
 ``limit``                non-negative int64  ``min``              document
 ``batchSize``            non-negative int64  ``noCursorTimeout``  bool
 ``exhaust``              bool                ``oplogReplay``      bool
-``hint``                 string or document  ``returnKey``        bool
-``allowPartialResults``  bool                ``showRecordId``     bool
-``awaitData``            bool                ``singleBatch``      bool
-``collation``            document            ``tailable``         bool
-``comment``              string
+``hint``                 string or document  ``readConcern``      document
+``allowPartialResults``  bool                ``returnKey``        bool
+``awaitData``            bool                ``sessionId``        (none)
+``collation``            document            ``showRecordId``     bool
+``comment``              string              ``singleBatch``      bool
 =======================  ==================  ===================  ==================
 
-All options are documented in the reference page for `the "find" command`_ in the MongoDB server manual, except for "maxAwaitTimeMS".
+All options are documented in the reference page for `the "find" command`_ in the MongoDB server manual, except for "maxAwaitTimeMS" and "sessionId".
 
 "maxAwaitTimeMS" is the maximum amount of time for the server to wait on new documents to satisfy a query, if "tailable" and "awaitData" are both true.
 If no new documents are found, the tailable cursor receives an empty batch. The "maxAwaitTimeMS" option is ignored for MongoDB older than 3.4.
 
+To add a "sessionId", construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session`. You can begin a transaction with :symbol:`mongoc_client_session_start_transaction`, optionally with a :symbol:`mongoc_transaction_opt_t` that overrides the options inherited from ``collection``. Then use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
+
+To add a "readConcern", construct a :symbol:`mongoc_read_concern_t` with :symbol:`mongoc_read_concern_new` and configure it with :symbol:`mongoc_read_concern_set_level`. Then use :symbol:`mongoc_read_concern_append` to add the read concern to ``opts``.
+
 For some options like "collation", the driver returns an error if the server version is too old to support the feature.
 Any fields in ``opts`` that are not listed here are passed to the server unmodified.