CDRIVER-3351 remaining retryable reads docs

kevinAlbs · kevinAlbs · commit ad5e2809e95f · 2019-08-30T13:03:44.000-04:00
diff --git a/src/libmongoc/doc/includes/not-retryable-read.txt b/src/libmongoc/doc/includes/not-retryable-read.txt
@@ -0,0 +1 @@
+This function is not considered a retryable read operation.
diff --git a/src/libmongoc/doc/includes/retryable-read-aggregate.txt b/src/libmongoc/doc/includes/retryable-read-aggregate.txt
@@ -0,0 +1,3 @@
+This function is considered a retryable read operation unless the pipeline contains a write stage like $out or $merge.
+Upon a transient error (a network error, errors due to replica set failover, etc.) the operation is safely retried once.
+If ``retryreads`` is false in the URI (see :symbol:`mongoc_uri_t`) the retry behavior does not apply.
diff --git a/src/libmongoc/doc/includes/retryable-read-command.txt b/src/libmongoc/doc/includes/retryable-read-command.txt
@@ -0,0 +1,2 @@
+Retry logic occurs regardless of the underlying command. Retrying ``mapReduce`` has the potential for degraded performance.
+Retrying a ``getMore`` command has the potential to miss results. For those commands, use generic command helpers (like |generic-cmd|) instead.
diff --git a/src/libmongoc/doc/includes/retryable-read.txt b/src/libmongoc/doc/includes/retryable-read.txt
@@ -0,0 +1,3 @@
+This function is considered a retryable read operation.
+Upon a transient error (a network error, errors due to replica set failover, etc.) the operation is safely retried once.
+If ``retryreads`` is false in the URI (see :symbol:`mongoc_uri_t`) the retry behavior does not apply.
diff --git a/src/libmongoc/doc/mongoc_client_command.rst b/src/libmongoc/doc/mongoc_client_command.rst
@@ -21,6 +21,8 @@ Synopsis
 
 This function is superseded by :symbol:`mongoc_client_command_with_opts()`, :symbol:`mongoc_client_read_command_with_opts()`, :symbol:`mongoc_client_write_command_with_opts()`, and :symbol:`mongoc_client_read_write_command_with_opts()`.
 
+.. include:: includes/not-retryable-read.txt
+
 Description
 -----------
 
diff --git a/src/libmongoc/doc/mongoc_client_command_simple.rst b/src/libmongoc/doc/mongoc_client_command_simple.rst
@@ -22,6 +22,8 @@ This is a simplified interface to :symbol:`mongoc_client_command()`. It returns
 
   ``reply`` is always set, and should be released with :symbol:`bson:bson_destroy()`.
 
+.. include:: includes/not-retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_client_command_simple_with_server_id.rst b/src/libmongoc/doc/mongoc_client_command_simple_with_server_id.rst
@@ -19,6 +19,8 @@ Synopsis
 
 This function executes a command on a specific server, using the database and command specification provided.
 
+.. include:: includes/not-retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_client_command_with_opts.rst b/src/libmongoc/doc/mongoc_client_command_with_opts.rst
@@ -26,6 +26,8 @@ Execute a command on the server, interpreting ``opts`` according to the MongoDB
 
 ``reply`` is always initialized, and must be freed with :symbol:`bson:bson_destroy()`.
 
+.. include:: includes/not-retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_client_find_databases_with_opts.rst b/src/libmongoc/doc/mongoc_client_find_databases_with_opts.rst
@@ -24,6 +24,8 @@ Parameters
 
 .. include:: includes/generic-opts.txt
 
+.. include:: includes/retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_client_get_database_names.rst b/src/libmongoc/doc/mongoc_client_get_database_names.rst
@@ -23,6 +23,8 @@ Description
 
 This function queries the MongoDB server for a list of known databases.
 
+.. include:: includes/retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_client_get_database_names_with_opts.rst b/src/libmongoc/doc/mongoc_client_get_database_names_with_opts.rst
@@ -26,6 +26,8 @@ Parameters
 
 .. include:: includes/generic-opts.txt
 
+.. include:: includes/retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_client_read_command_with_opts.rst b/src/libmongoc/doc/mongoc_client_read_command_with_opts.rst
@@ -25,6 +25,10 @@ Execute a command on the server, applying logic that is specific to commands tha
 
 ``reply`` is always initialized, and must be freed with :symbol:`bson:bson_destroy()`.
 
+.. |generic-cmd| replace:: :symbol:`mongoc_client_command_with_opts`
+.. include:: includes/retryable-read.txt
+.. include:: includes/retryable-read-command.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_client_watch.rst b/src/libmongoc/doc/mongoc_client_watch.rst
@@ -24,6 +24,8 @@ will be used. This may happen if the change stream encounters a resumable error.
 
    A change stream is only supported with majority read concern.
 
+.. include:: includes/retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_collection_aggregate.rst b/src/libmongoc/doc/mongoc_collection_aggregate.rst
@@ -37,6 +37,9 @@ Parameters
 
 For a list of all options, see `the MongoDB Manual entry on the aggregate command <http://docs.mongodb.org/manual/reference/command/aggregate/>`_.
 
+
+.. include:: includes/retryable-read-aggregate.txt
+
 Description
 -----------
 
diff --git a/src/libmongoc/doc/mongoc_collection_command.rst b/src/libmongoc/doc/mongoc_collection_command.rst
@@ -21,6 +21,8 @@ Synopsis
 
 This function is superseded by :symbol:`mongoc_collection_command_with_opts()`, :symbol:`mongoc_collection_read_command_with_opts()`, :symbol:`mongoc_collection_write_command_with_opts()`, and :symbol:`mongoc_collection_read_write_command_with_opts()`.
 
+.. include:: includes/not-retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_collection_command_simple.rst b/src/libmongoc/doc/mongoc_collection_command_simple.rst
@@ -31,6 +31,8 @@ This is a simplified version of :symbol:`mongoc_collection_command()` that retur
 
 This function tries to unwrap an embedded error in the command when possible. The unwrapped error will be propagated via the ``error`` parameter. Additionally, the result document is set in ``reply``.
 
+.. include:: includes/not-retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_collection_command_with_opts.rst b/src/libmongoc/doc/mongoc_collection_command_with_opts.rst
@@ -39,6 +39,8 @@ Parameters
 
 Consult `the MongoDB Manual entry on Database Commands <https://docs.mongodb.com/manual/reference/command/>`_ for each command's arguments.
 
+.. include:: includes/not-retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_collection_count.rst b/src/libmongoc/doc/mongoc_collection_count.rst
@@ -13,6 +13,8 @@ Use :symbol:`mongoc_collection_count_documents` or :symbol:`mongoc_collection_es
 
 :symbol:`mongoc_collection_estimated_document_count` has the same performance as calling :symbol:`mongoc_collection_count` with a NULL ``query``, but is not guaranteed to retrieve an accurate collection count.
 
+.. include:: includes/retryable-read.txt
+
 Synopsis
 --------
 
diff --git a/src/libmongoc/doc/mongoc_collection_count_documents.rst b/src/libmongoc/doc/mongoc_collection_count_documents.rst
@@ -37,6 +37,8 @@ Description
 
 This functions executes a count query on ``collection``. In contrast with :symbol:`mongoc_collection_estimated_document_count()`, the count returned is guaranteed to be accurate.
 
+.. include:: includes/retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_collection_count_with_opts.rst b/src/libmongoc/doc/mongoc_collection_count_with_opts.rst
@@ -57,6 +57,8 @@ In addition to the standard functionality available from mongoc_collection_count
 
 For more information, see the `query reference <http://docs.mongodb.org/manual/reference/operator/query/>`_ at the MongoDB website.
 
+.. include:: includes/retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_collection_estimated_document_count.rst b/src/libmongoc/doc/mongoc_collection_estimated_document_count.rst
@@ -35,6 +35,8 @@ Description
 
 This functions executes a count query on ``collection``. In contrast with :symbol:`mongoc_collection_count_documents()`, the count returned is *not* guaranteed to be accurate.
 
+.. include:: includes/retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_collection_find.rst b/src/libmongoc/doc/mongoc_collection_find.rst
@@ -46,6 +46,8 @@ This function shall execute a query on the underlying ``collection``.
 
 If no options are necessary, ``query`` can simply contain a query such as ``{a:1}``. If you would like to specify options such as a sort order, the query must be placed inside of ``{"$query": {}}``. See the example below for how to properly specify additional options to ``query``.
 
+.. include:: includes/retryable-read.txt
+
 Returns
 -------
 
diff --git a/src/libmongoc/doc/mongoc_collection_find_indexes.rst b/src/libmongoc/doc/mongoc_collection_find_indexes.rst
@@ -21,6 +21,8 @@ Please use :symbol:`mongoc_collection_find_indexes_with_opts()` instead.
 
 Fetches a cursor containing documents, each corresponding to an index on this collection.
 
+.. include:: includes/retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_collection_find_indexes_with_opts.rst b/src/libmongoc/doc/mongoc_collection_find_indexes_with_opts.rst
@@ -14,6 +14,8 @@ Synopsis
 
 Fetches a cursor containing documents, each corresponding to an index on this collection.
 
+.. include:: includes/retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_collection_find_with_opts.rst b/src/libmongoc/doc/mongoc_collection_find_with_opts.rst
@@ -34,6 +34,8 @@ To target a specific server, include an integer "serverId" field in ``opts`` wit
 
 .. include:: includes/read-opts-sources.txt
 
+.. include:: includes/retryable-read.txt
+
 Returns
 -------
 
diff --git a/src/libmongoc/doc/mongoc_collection_read_command_with_opts.rst b/src/libmongoc/doc/mongoc_collection_read_command_with_opts.rst
@@ -24,6 +24,10 @@ Execute a command on the server, applying logic that is specific to commands tha
 
 ``reply`` is always initialized, and must be freed with :symbol:`bson:bson_destroy()`.
 
+.. include:: includes/retryable-read.txt
+.. |generic-cmd| replace:: :symbol:`mongoc_collection_command_with_opts`
+.. include:: includes/retryable-read-command.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_collection_watch.rst b/src/libmongoc/doc/mongoc_collection_watch.rst
@@ -24,6 +24,8 @@ will be used. This may happen if the change stream encounters a resumable error.
 
    A change stream is only supported with majority read concern.
 
+.. include:: includes/retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_database_aggregate.rst b/src/libmongoc/doc/mongoc_database_aggregate.rst
@@ -52,6 +52,8 @@ Transaction        Transaction    Transaction
 
 :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>`.
 
+.. include:: includes/retryable-read-aggregate.txt
+
 Returns
 -------
 
diff --git a/src/libmongoc/doc/mongoc_database_command.rst b/src/libmongoc/doc/mongoc_database_command.rst
@@ -25,6 +25,8 @@ Description
 
 This function creates a cursor which will execute the command when :symbol:`mongoc_cursor_next` is called on it. The database's read preference, read concern, and write concern are not applied to the command, and :symbol:`mongoc_cursor_next` will not check the server response for a write concern error or write concern timeout.
 
+.. include:: includes/not-retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_database_command_simple.rst b/src/libmongoc/doc/mongoc_database_command_simple.rst
@@ -26,6 +26,8 @@ Parameters
 
 This is a simplified interface to :symbol:`mongoc_database_command()` that returns the first result document. The database's read preference, read concern, and write concern are not applied to the command.  The parameter ``reply`` is initialized even upon failure to simplify memory management.
 
+.. include:: includes/not-retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_database_command_with_opts.rst b/src/libmongoc/doc/mongoc_database_command_with_opts.rst
@@ -25,6 +25,8 @@ Execute a command on the server, interpreting ``opts`` according to the MongoDB
 
 ``reply`` is always initialized, and must be freed with :symbol:`bson:bson_destroy()`.
 
+.. include:: includes/not-retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_database_find_collections.rst b/src/libmongoc/doc/mongoc_database_find_collections.rst
@@ -26,6 +26,8 @@ Description
 
 Fetches a cursor containing documents, each corresponding to a collection on this database.
 
+.. include:: includes/retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_database_find_collections_with_opts.rst b/src/libmongoc/doc/mongoc_database_find_collections_with_opts.rst
@@ -16,6 +16,8 @@ Fetches a cursor containing documents, each corresponding to a collection on thi
 
 To get collection names only, use :symbol:`mongoc_database_get_collection_names_with_opts`.
 
+.. include:: includes/retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_database_get_collection_names.rst b/src/libmongoc/doc/mongoc_database_get_collection_names.rst
@@ -24,6 +24,8 @@ Description
 
 Fetches a ``NULL`` terminated array of ``NULL-byte`` terminated ``char*`` strings containing the names of all of the collections in ``database``.
 
+.. include:: includes/retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_database_get_collection_names_with_opts.rst b/src/libmongoc/doc/mongoc_database_get_collection_names_with_opts.rst
@@ -15,6 +15,8 @@ Synopsis
 
 Fetches a ``NULL`` terminated array of ``NULL-byte`` terminated ``char*`` strings containing the names of all of the collections in ``database``.
 
+.. include:: includes/retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_database_read_command_with_opts.rst b/src/libmongoc/doc/mongoc_database_read_command_with_opts.rst
@@ -24,6 +24,10 @@ Execute a command on the server, applying logic that is specific to commands tha
 
 ``reply`` is always initialized, and must be freed with :symbol:`bson:bson_destroy()`.
 
+.. |generic-cmd| replace:: :symbol:`mongoc_database_command_with_opts`
+.. include:: includes/retryable-read.txt
+.. include:: includes/retryable-read-command.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_database_watch.rst b/src/libmongoc/doc/mongoc_database_watch.rst
@@ -24,6 +24,8 @@ will be used. This may happen if the change stream encounters a resumable error.
 
    A change stream is only supported with majority read concern.
 
+.. include:: includes/retryable-read.txt
+
 Parameters
 ----------
 
diff --git a/src/libmongoc/doc/mongoc_gridfs_bucket_download_to_stream.rst b/src/libmongoc/doc/mongoc_gridfs_bucket_download_to_stream.rst
@@ -30,6 +30,8 @@ Reads from the GridFS file and writes to the ``destination`` stream.
 Writes the full contents of the file to the ``destination`` stream.
 The ``destination`` stream is not closed after calling :symbol:`mongoc_gridfs_bucket_download_to_stream()`; call :symbol:`mongoc_stream_close()` after.
 
+.. include:: includes/retryable-read.txt
+
 See Also
 --------
 :symbol:`mongoc_stream_file_new` and :symbol:`mongoc_stream_file_new_for_path`, which can be used to create a destination stream from a file.
diff --git a/src/libmongoc/doc/mongoc_gridfs_bucket_find.rst b/src/libmongoc/doc/mongoc_gridfs_bucket_find.rst
@@ -25,6 +25,8 @@ Description
 
 Finds file documents from the bucket's ``files`` collection.
 
+.. include:: includes/retryable-read.txt
+
 Returns
 -------
 A newly allocated :symbol:`mongoc_cursor_t` that must be freed with :symbol:`mongoc_cursor_destroy()`.
diff --git a/src/libmongoc/doc/mongoc_gridfs_find.rst b/src/libmongoc/doc/mongoc_gridfs_find.rst
@@ -28,6 +28,8 @@ Description
 
 Finds all gridfs files matching ``query``. You can iterate the matched gridfs files with the resulting file list.
 
+.. include:: includes/retryable-read.txt
+
 Returns
 -------
 
diff --git a/src/libmongoc/doc/mongoc_gridfs_find_one.rst b/src/libmongoc/doc/mongoc_gridfs_find_one.rst
@@ -31,6 +31,8 @@ Description
 
 This function shall execute a query on the underlying gridfs implementation. The first file matching ``query`` will be returned. If there is an error, NULL is returned and ``error`` is filled out; if there is no error but no matching file is found, NULL is returned and the error code and domain are 0.
 
+.. include:: includes/retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_gridfs_find_one_by_filename.rst b/src/libmongoc/doc/mongoc_gridfs_find_one_by_filename.rst
@@ -25,6 +25,8 @@ Description
 
 Finds the first file matching the filename specified. If there is an error, NULL is returned and ``error`` is filled out; if there is no error but no matching file is found, NULL is returned and the error code and domain are 0.
 
+.. include:: includes/retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_gridfs_find_one_with_opts.rst b/src/libmongoc/doc/mongoc_gridfs_find_one_with_opts.rst
@@ -30,6 +30,8 @@ Find the first GridFS file matching ``filter``. If there is an error, NULL is re
 
 See :symbol:`mongoc_collection_find_with_opts` for a description of the ``filter`` and ``opts`` parameters.
 
+.. include:: includes/retryable-read.txt
+
 Errors
 ------
 
diff --git a/src/libmongoc/doc/mongoc_gridfs_find_with_opts.rst b/src/libmongoc/doc/mongoc_gridfs_find_with_opts.rst
@@ -27,6 +27,8 @@ Finds all gridfs files matching ``filter``. You can iterate the matched gridfs f
 
 See :symbol:`mongoc_collection_find_with_opts` for a description of the ``filter`` and ``opts`` parameters.
 
+.. include:: includes/retryable-read.txt
+
 Returns
 -------
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+This function is not considered a retryable read operation.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+This function is considered a retryable read operation unless the pipeline contains a write stage like $out or $merge.`
	`2`	`+Upon a transient error (a network error, errors due to replica set failover, etc.) the operation is safely retried once.`
	`3`	+If ``retryreads`` is false in the URI (see :symbol:`mongoc_uri_t`) the retry behavior does not apply.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Retry logic occurs regardless of the underlying command. Retrying ``mapReduce`` has the potential for degraded performance.
	`2`	+Retrying a ``getMore`` command has the potential to miss results. For those commands, use generic command helpers (like \|generic-cmd\|) instead.