CDRIVER-1431 document pool's thread safety

Author: ajdavis

doc/includes/mongoc_client_pool_call_once.txt

@@ -0,0 +1,4 @@
+Thread Safety
+-------------
+
+This function can only be called once on a pool, and must be called before the first call to :symbol:`mongoc_client_pool_pop`.

doc/includes/mongoc_client_pool_thread_safe.txt

@@ -0,0 +1,4 @@
+Thread Safety
+-------------
+
+This function is safe to call from multiple threads.

doc/mongoc_client_pool_max_size.rst

@@ -20,3 +20,4 @@ Parameters
 * ``pool``: A :symbol:`mongoc_client_pool_t <mongoc_client_pool_t>`.
 * ``max_pool_size``: The maximum number of connections which shall be available from the pool.
 
+.. include:: includes/mongoc_client_pool_thread_safe.txt

doc/mongoc_client_pool_min_size.rst

@@ -20,3 +20,6 @@ Parameters
 * ``pool``: A :symbol:`mongoc_client_pool_t <mongoc_client_pool_t>`.
 * ``min_pool_size``: The minimum number of connections which shall be kept in the pool.
 
+.. include:: includes/mongoc_client_pool_thread_safe.txt
+
+Subsequent calls to :symbol:`mongoc_client_pool_push` respect the new minimum size, and close the least recently used :symbol:`mongoc_client_t` if the minimum size is exceeded.

doc/mongoc_client_pool_pop.rst

@@ -23,3 +23,4 @@ Returns
 
 A :symbol:`mongoc_client_t <mongoc_client_t>`.
 
+.. include:: includes/mongoc_client_pool_thread_safe.txt

doc/mongoc_client_pool_push.rst

@@ -19,3 +19,4 @@ Parameters
 * ``pool``: A :symbol:`mongoc_client_pool_t <mongoc_client_pool_t>`.
 * ``client``: A :symbol:`mongoc_client_t <mongoc_client_t>`.
 
+.. include:: includes/mongoc_client_pool_thread_safe.txt

doc/mongoc_client_pool_set_apm_callbacks.rst

@@ -15,8 +15,6 @@ Synopsis
 
 Register a set of callbacks to receive Application Performance Monitoring events.
 
-This function can only be called once on a pool, and must be called before the first :symbol:`mongoc_client_pool_pop <mongoc_client_pool_pop>`.
-
 Parameters
 ----------
 
@@ -29,6 +27,8 @@ Returns
 
 Returns true on success, otherwise false and an error is logged.
 
+.. include:: includes/mongoc_client_pool_call_once.txt
+
 See Also
 --------
 

doc/mongoc_client_pool_set_appname.rst

@@ -13,8 +13,6 @@ Synopsis
 
 This function is identical to :symbol:`mongoc_client_set_appname() <mongoc_client_set_appname>` except for client pools.
 
-This function can only be called once on a pool, and must be called before the first :symbol:`mongoc_client_pool_pop <mongoc_client_pool_pop>`.
-
 Also note that :symbol:`mongoc_client_set_appname() <mongoc_client_set_appname>` cannot be called on a client retrieved from a client pool.
 
 Parameters
@@ -28,3 +26,4 @@ Returns
 
 true if the appname is set successfully. Otherwise, false.
 
+.. include:: includes/mongoc_client_pool_call_once.txt

doc/mongoc_client_pool_set_error_api.rst

@@ -25,3 +25,4 @@ Returns
 
 Returns true if the error API version was set, or logs an error message and returns false.
 
+.. include:: includes/mongoc_client_pool_call_once.txt

doc/mongoc_client_pool_set_ssl_opts.rst

@@ -16,8 +16,6 @@ Synopsis
 
 This function is identical to :symbol:`mongoc_client_set_ssl_opts() <mongoc_client_set_ssl_opts>` except for client pools. It ensures that all clients retrieved from :symbol:`mongoc_client_pool_pop() <mongoc_client_pool_pop>` or :symbol:`mongoc_client_pool_try_pop() <mongoc_client_pool_try_pop>` are configured with the same SSL settings.
 
-It is a programming error to call this function after retrieving a client from the client pool.
-
 Beginning in version 1.2.0, once a pool has any SSL options set, all connections use SSL, even if ``ssl=true`` is omitted from the MongoDB URI. Before, SSL options were ignored unless ``ssl=true`` was included in the URI.
 
 Parameters
@@ -26,6 +24,8 @@ Parameters
 * ``pool``: A :symbol:`mongoc_client_pool_t <mongoc_client_pool_t>`.
 * ``opts``: A :symbol:`mongoc_ssl_opt_t <mongoc_ssl_opt_t>` that will not be modified.
 
+.. include:: includes/mongoc_client_pool_call_once.txt
+
 Availability
 ------------