CDRIVER-5571 deprecate *_hint for *_server_id (#1601)

kevinAlbs · web-flow · commit c6dc48dc02d7 · 2024-05-17T12:33:42.000-04:00
* deprecate `*_hint` functions for newly added `*_server_id` functions

* call `*_server_id` functions from `*_hint`

* update calls to use new `*_server_id` functions

* update docs

* update NEWS
diff --git a/NEWS b/NEWS
@@ -1,3 +1,14 @@
+libmongoc 1.28.0 (unreleased)
+=============================
+
+Deprecated:
+
+  * Use of `*_hint` functions is deprecated in favor of more aptly named `*_server_id` functions:
+    * `mongoc_bulk_operation_set_hint` is deprecated for `mongoc_bulk_operation_set_server_id`
+    * `mongoc_bulk_operation_get_hint` is deprecated for `mongoc_bulk_operation_get_server_id`
+    * `mongoc_cursor_set_hint` is deprecated for `mongoc_cursor_set_server_id`
+    * `mongoc_cursor_get_hint` is deprecated for `mongoc_cursor_get_server_id`
+
 libmongoc 1.27.1
 ================
 
diff --git a/src/libmongoc/doc/mongoc_bulk_operation_execute.rst b/src/libmongoc/doc/mongoc_bulk_operation_execute.rst
@@ -46,5 +46,5 @@ The ``reply`` document counts operations and collects error information. See `Bu
 
   | `Bulk Write Operations <bulk_>`_
 
-  | :symbol:`mongoc_bulk_operation_get_hint`, which gets the id of the server used even if the operation failed.
+  | :symbol:`mongoc_bulk_operation_get_server_id`, which gets the id of the server used even if the operation failed.
 
diff --git a/src/libmongoc/doc/mongoc_bulk_operation_get_hint.rst b/src/libmongoc/doc/mongoc_bulk_operation_get_hint.rst
@@ -3,13 +3,21 @@
 mongoc_bulk_operation_get_hint()
 ================================
 
+.. warning::
+   .. deprecated:: 1.28.0
+
+      This function is deprecated and should not be used in new code.
+
+      Please use :symbol:`mongoc_bulk_operation_get_server_id()` in new code.
+
 Synopsis
 --------
 
 .. code-block:: c
 
   uint32_t
-  mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk);
+  mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk)
+    BSON_GNUC_DEPRECATED_FOR (mongoc_bulk_operation_get_server_id);
 
 Parameters
 ----------
diff --git a/src/libmongoc/doc/mongoc_bulk_operation_get_server_id.rst b/src/libmongoc/doc/mongoc_bulk_operation_get_server_id.rst
@@ -0,0 +1,25 @@
+:man_page: mongoc_bulk_operation_get_server_id
+
+mongoc_bulk_operation_get_server_id()
+=====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  uint32_t
+  mongoc_bulk_operation_get_server_id (const mongoc_bulk_operation_t *bulk);
+
+Parameters
+----------
+
+* ``bulk``: A :symbol:`mongoc_bulk_operation_t`.
+
+Description
+-----------
+
+Retrieves the opaque id of the server used for the operation.
+
+This number is zero until the driver actually uses a server in :symbol:`mongoc_bulk_operation_execute`. The server id is the same number as the return value of a successful :symbol:`mongoc_bulk_operation_execute`, so ``mongoc_bulk_operation_get_server_id`` is useful mainly in case :symbol:`mongoc_bulk_operation_execute` fails and returns zero.
+
diff --git a/src/libmongoc/doc/mongoc_bulk_operation_set_hint.rst b/src/libmongoc/doc/mongoc_bulk_operation_set_hint.rst
@@ -3,14 +3,21 @@
 mongoc_bulk_operation_set_hint()
 ================================
 
+.. warning::
+   .. deprecated:: 1.28.0
+
+      This function is deprecated and should not be used in new code.
+
+      Please use :symbol:`mongoc_bulk_operation_set_server_id()` in new code.
+
 Synopsis
 --------
 
 .. code-block:: c
 
   void
-  mongoc_bulk_operation_set_hint (const mongoc_bulk_operation_t *bulk,
-                                  uint32_t server_id);
+  mongoc_bulk_operation_set_hint (mongoc_bulk_operation_t *bulk, uint32_t server_id)
+    BSON_GNUC_DEPRECATED_FOR (mongoc_bulk_operation_set_server_id);
 
 Parameters
 ----------
diff --git a/src/libmongoc/doc/mongoc_bulk_operation_set_server_id.rst b/src/libmongoc/doc/mongoc_bulk_operation_set_server_id.rst
@@ -0,0 +1,26 @@
+:man_page: mongoc_bulk_operation_set_server_id
+
+mongoc_bulk_operation_set_server_id()
+=====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_bulk_operation_set_server_id (mongoc_bulk_operation_t *bulk, uint32_t server_id);
+
+Parameters
+----------
+
+* ``bulk``: A :symbol:`mongoc_bulk_operation_t`.
+* ``server_id``: An opaque id identifying the server to use.
+
+Description
+-----------
+
+Specifies which server to use for the operation. This function has an effect only if called before :symbol:`mongoc_bulk_operation_execute`.
+
+Use ``mongoc_bulk_operation_set_server_id`` only for building a language driver that wraps the C Driver. When writing applications in C, leave the server id unset and allow the driver to choose a suitable server for the bulk operation.
+
diff --git a/src/libmongoc/doc/mongoc_bulk_operation_t.rst b/src/libmongoc/doc/mongoc_bulk_operation_t.rst
@@ -47,6 +47,7 @@ After adding all of the write operations to the :symbol:`mongoc_bulk_operation_t
     mongoc_bulk_operation_destroy
     mongoc_bulk_operation_execute
     mongoc_bulk_operation_get_hint
+    mongoc_bulk_operation_get_server_id
     mongoc_bulk_operation_get_write_concern
     mongoc_bulk_operation_insert
     mongoc_bulk_operation_insert_with_opts
@@ -60,6 +61,7 @@ After adding all of the write operations to the :symbol:`mongoc_bulk_operation_t
     mongoc_bulk_operation_set_client_session
     mongoc_bulk_operation_set_comment
     mongoc_bulk_operation_set_hint
+    mongoc_bulk_operation_set_server_id
     mongoc_bulk_operation_set_let
     mongoc_bulk_operation_update
     mongoc_bulk_operation_update_many_with_opts
diff --git a/src/libmongoc/doc/mongoc_cursor_get_hint.rst b/src/libmongoc/doc/mongoc_cursor_get_hint.rst
@@ -3,13 +3,20 @@
 mongoc_cursor_get_hint()
 ========================
 
+.. warning::
+   .. deprecated:: 1.28.0
+
+      This function is deprecated and should not be used in new code.
+
+      Please use :symbol:`mongoc_cursor_get_server_id()` in new code.
+
 Synopsis
 --------
 
 .. code-block:: c
 
   uint32_t
-  mongoc_cursor_get_hint (const mongoc_cursor_t *cursor);
+  mongoc_cursor_get_hint (const mongoc_cursor_t *cursor) BSON_GNUC_DEPRECATED_FOR (mongoc_cursor_get_server_id);
 
 Parameters
 ----------
@@ -23,5 +30,5 @@ Retrieves the opaque id of the server used for the operation.
 
 (The function name includes the old term "hint" for the sake of backward compatibility, but we now call this number a "server id".)
 
-This number is zero until the driver actually uses a server when executing the find operation or :symbol:`mongoc_cursor_set_hint` is called.
+This number is zero until the driver actually uses a server when executing the find operation or :symbol:`mongoc_cursor_set_server_id` is called.
 
diff --git a/src/libmongoc/doc/mongoc_cursor_get_server_id.rst b/src/libmongoc/doc/mongoc_cursor_get_server_id.rst
@@ -0,0 +1,25 @@
+:man_page: mongoc_cursor_get_server_id
+
+mongoc_cursor_get_server_id()
+=============================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  uint32_t
+  mongoc_cursor_get_server_id (const mongoc_cursor_t *cursor);
+
+Parameters
+----------
+
+* ``cursor``: A :symbol:`mongoc_cursor_t`.
+
+Description
+-----------
+
+Retrieves the opaque id of the server used for the operation.
+
+This number is zero until the driver actually uses a server when executing the find operation or :symbol:`mongoc_cursor_set_server_id` is called.
+
diff --git a/src/libmongoc/doc/mongoc_cursor_set_hint.rst b/src/libmongoc/doc/mongoc_cursor_set_hint.rst
@@ -3,13 +3,21 @@
 mongoc_cursor_set_hint()
 ========================
 
+.. warning::
+   .. deprecated:: 1.28.0
+
+      This function is deprecated and should not be used in new code.
+
+      Please use :symbol:`mongoc_cursor_set_server_id()` in new code.
+
 Synopsis
 --------
 
 .. code-block:: c
 
   bool
-  mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id);
+  mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id)
+    BSON_GNUC_DEPRECATED_FOR (mongoc_cursor_set_server_id);
 
 Parameters
 ----------
diff --git a/src/libmongoc/doc/mongoc_cursor_set_server_id.rst b/src/libmongoc/doc/mongoc_cursor_set_server_id.rst
@@ -0,0 +1,31 @@
+:man_page: mongoc_cursor_set_server_id
+
+mongoc_cursor_set_server_id()
+=============================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  mongoc_cursor_set_server_id (mongoc_cursor_t *cursor, uint32_t server_id)
+
+Parameters
+----------
+
+* ``cursor``: A :symbol:`mongoc_cursor_t`.
+* ``server_id``: An opaque id identifying the server to use.
+
+Description
+-----------
+
+Specifies which server to use for the operation. This function has an effect only if called before the find operation is executed.
+
+Use ``mongoc_cursor_set_server_id`` only for building a language driver that wraps the C Driver. When writing applications in C, leave the server id unset and allow the driver to choose a suitable server from the find operation's read preference.
+
+Returns
+-------
+
+Returns true on success. If any arguments are invalid, returns false and logs an error.
+
diff --git a/src/libmongoc/doc/mongoc_cursor_t.rst b/src/libmongoc/doc/mongoc_cursor_t.rst
@@ -52,6 +52,7 @@ Example
     mongoc_cursor_error_document
     mongoc_cursor_get_batch_size
     mongoc_cursor_get_hint
+    mongoc_cursor_get_server_id
     mongoc_cursor_get_host
     mongoc_cursor_get_id
     mongoc_cursor_get_limit
@@ -63,6 +64,7 @@ Example
     mongoc_cursor_next
     mongoc_cursor_set_batch_size
     mongoc_cursor_set_hint
+    mongoc_cursor_set_server_id
     mongoc_cursor_set_limit
     mongoc_cursor_set_max_await_time_ms
 
diff --git a/src/libmongoc/src/mongoc/mongoc-bulk-operation.c b/src/libmongoc/src/mongoc/mongoc-bulk-operation.c
@@ -913,15 +913,26 @@ mongoc_bulk_operation_set_client_session (mongoc_bulk_operation_t *bulk,
 
 uint32_t
 mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk)
+{
+   return mongoc_bulk_operation_get_server_id (bulk);
+}
+
+uint32_t
+mongoc_bulk_operation_get_server_id (const mongoc_bulk_operation_t *bulk)
 {
    BSON_ASSERT_PARAM (bulk);
 
    return bulk->server_id;
 }
 
-
 void
 mongoc_bulk_operation_set_hint (mongoc_bulk_operation_t *bulk, uint32_t server_id)
+{
+   mongoc_bulk_operation_set_server_id (bulk, server_id);
+}
+
+void
+mongoc_bulk_operation_set_server_id (mongoc_bulk_operation_t *bulk, uint32_t server_id)
 {
    BSON_ASSERT_PARAM (bulk);
 
diff --git a/src/libmongoc/src/mongoc/mongoc-bulk-operation.h b/src/libmongoc/src/mongoc/mongoc-bulk-operation.h
@@ -131,12 +131,18 @@ mongoc_bulk_operation_set_client (mongoc_bulk_operation_t *bulk, void *client);
 MONGOC_EXPORT (void)
 mongoc_bulk_operation_set_client_session (mongoc_bulk_operation_t *bulk,
                                           struct _mongoc_client_session_t *client_session);
-/* These names include the term "hint" for backward compatibility, should be
- * mongoc_bulk_operation_get_server_id, mongoc_bulk_operation_set_server_id. */
+// `mongoc_bulk_operation_set_hint` is deprecated for the more aptly named `mongoc_bulk_operation_set_server_id`.
 MONGOC_EXPORT (void)
-mongoc_bulk_operation_set_hint (mongoc_bulk_operation_t *bulk, uint32_t server_id);
+mongoc_bulk_operation_set_hint (mongoc_bulk_operation_t *bulk, uint32_t server_id)
+   BSON_GNUC_DEPRECATED_FOR (mongoc_bulk_operation_set_server_id);
+MONGOC_EXPORT (void)
+mongoc_bulk_operation_set_server_id (mongoc_bulk_operation_t *bulk, uint32_t server_id);
+// `mongoc_bulk_operation_get_hint` is deprecated for the more aptly named `mongoc_bulk_operation_get_server_id`.
+MONGOC_EXPORT (uint32_t)
+mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk)
+   BSON_GNUC_DEPRECATED_FOR (mongoc_bulk_operation_get_server_id);
 MONGOC_EXPORT (uint32_t)
-mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk);
+mongoc_bulk_operation_get_server_id (const mongoc_bulk_operation_t *bulk);
 MONGOC_EXPORT (const mongoc_write_concern_t *)
 mongoc_bulk_operation_get_write_concern (const mongoc_bulk_operation_t *bulk);
 BSON_END_DECLS
diff --git a/src/libmongoc/src/mongoc/mongoc-cursor.c b/src/libmongoc/src/mongoc/mongoc-cursor.c
@@ -291,7 +291,7 @@ _mongoc_cursor_new_with_opts (mongoc_client_t *client,
       }
 
       if (server_id) {
-         (void) mongoc_cursor_set_hint (cursor, server_id);
+         (void) mongoc_cursor_set_server_id (cursor, server_id);
       }
 
       // Selectively copy the options:
@@ -1437,16 +1437,22 @@ mongoc_cursor_get_limit (const mongoc_cursor_t *cursor)
 
 bool
 mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id)
+{
+   return mongoc_cursor_set_server_id (cursor, server_id);
+}
+
+bool
+mongoc_cursor_set_server_id (mongoc_cursor_t *cursor, uint32_t server_id)
 {
    BSON_ASSERT (cursor);
 
    if (cursor->server_id) {
-      MONGOC_ERROR ("mongoc_cursor_set_hint: server_id already set");
+      MONGOC_ERROR ("mongoc_cursor_set_server_id: server_id already set");
       return false;
    }
 
    if (!server_id) {
-      MONGOC_ERROR ("mongoc_cursor_set_hint: cannot set server_id to 0");
+      MONGOC_ERROR ("mongoc_cursor_set_server_id: cannot set server_id to 0");
       return false;
    }
 
@@ -1458,6 +1464,12 @@ mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id)
 
 uint32_t
 mongoc_cursor_get_hint (const mongoc_cursor_t *cursor)
+{
+   return mongoc_cursor_get_server_id (cursor);
+}
+
+uint32_t
+mongoc_cursor_get_server_id (const mongoc_cursor_t *cursor)
 {
    BSON_ASSERT (cursor);
 
diff --git a/src/libmongoc/src/mongoc/mongoc-cursor.h b/src/libmongoc/src/mongoc/mongoc-cursor.h
@@ -59,12 +59,17 @@ MONGOC_EXPORT (bool)
 mongoc_cursor_set_limit (mongoc_cursor_t *cursor, int64_t limit);
 MONGOC_EXPORT (int64_t)
 mongoc_cursor_get_limit (const mongoc_cursor_t *cursor);
-/* These names include the term "hint" for backward compatibility, should be
- * mongoc_cursor_get_server_id, mongoc_cursor_set_server_id. */
+// `mongoc_cursor_set_hint` is deprecated for more aptly named `mongoc_cursor_set_server_id`.
 MONGOC_EXPORT (bool)
-mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id);
+mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id)
+   BSON_GNUC_DEPRECATED_FOR (mongoc_cursor_set_server_id);
+MONGOC_EXPORT (bool)
+mongoc_cursor_set_server_id (mongoc_cursor_t *cursor, uint32_t server_id);
+// `mongoc_cursor_get_hint` is deprecated for more aptly named `mongoc_cursor_get_server_id`.
+MONGOC_EXPORT (uint32_t)
+mongoc_cursor_get_hint (const mongoc_cursor_t *cursor) BSON_GNUC_DEPRECATED_FOR (mongoc_cursor_get_server_id);
 MONGOC_EXPORT (uint32_t)
-mongoc_cursor_get_hint (const mongoc_cursor_t *cursor);
+mongoc_cursor_get_server_id (const mongoc_cursor_t *cursor);
 MONGOC_EXPORT (int64_t)
 mongoc_cursor_get_id (const mongoc_cursor_t *cursor);
 MONGOC_EXPORT (void)
diff --git a/src/libmongoc/tests/test-mongoc-bulk.c b/src/libmongoc/tests/test-mongoc-bulk.c
diff --git a/src/libmongoc/tests/test-mongoc-client.c b/src/libmongoc/tests/test-mongoc-client.c
diff --git a/src/libmongoc/tests/test-mongoc-collection.c b/src/libmongoc/tests/test-mongoc-collection.c
diff --git a/src/libmongoc/tests/test-mongoc-cursor.c b/src/libmongoc/tests/test-mongoc-cursor.c
diff --git a/src/libmongoc/tests/test-mongoc-exhaust.c b/src/libmongoc/tests/test-mongoc-exhaust.c
diff --git a/src/libmongoc/tests/test-mongoc-retryable-writes.c b/src/libmongoc/tests/test-mongoc-retryable-writes.c

Original file line number	Diff line number	Diff line change
@@ -46,5 +46,5 @@ The ``reply`` document counts operations and collects error information. See `Bu
`46`	`46`
`47`	`47`	\| `Bulk Write Operations <bulk_>`_
`48`	`48`
`49`		- \| :symbol:`mongoc_bulk_operation_get_hint`, which gets the id of the server used even if the operation failed.
	`49`	+ \| :symbol:`mongoc_bulk_operation_get_server_id`, which gets the id of the server used even if the operation failed.
`50`	`50`