Skip to content

Commit c6dc48d

Browse files
kevinAlbskevinAlbs
authored
CDRIVER-5571 deprecate *_hint for *_server_id (#1601)
* 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
1 parent cc3ed2c commit c6dc48d

22 files changed

+249
-63
lines changed

‎NEWS

+11
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
libmongoc 1.28.0 (unreleased)
2+
=============================
3+
4+
Deprecated:
5+
6+
* Use of `*_hint` functions is deprecated in favor of more aptly named `*_server_id` functions:
7+
* `mongoc_bulk_operation_set_hint` is deprecated for `mongoc_bulk_operation_set_server_id`
8+
* `mongoc_bulk_operation_get_hint` is deprecated for `mongoc_bulk_operation_get_server_id`
9+
* `mongoc_cursor_set_hint` is deprecated for `mongoc_cursor_set_server_id`
10+
* `mongoc_cursor_get_hint` is deprecated for `mongoc_cursor_get_server_id`
11+
112
libmongoc 1.27.1
213
================
314

‎src/libmongoc/doc/mongoc_bulk_operation_execute.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -46,5 +46,5 @@ The ``reply`` document counts operations and collects error information. See `Bu
4646

4747
| `Bulk Write Operations <bulk_>`_
4848
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.
5050

‎src/libmongoc/doc/mongoc_bulk_operation_get_hint.rst

+9-1
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,21 @@
33
mongoc_bulk_operation_get_hint()
44
================================
55

6+
.. warning::
7+
.. deprecated:: 1.28.0
8+
9+
This function is deprecated and should not be used in new code.
10+
11+
Please use :symbol:`mongoc_bulk_operation_get_server_id()` in new code.
12+
613
Synopsis
714
--------
815

916
.. code-block:: c
1017
1118
uint32_t
12-
mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk);
19+
mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk)
20+
BSON_GNUC_DEPRECATED_FOR (mongoc_bulk_operation_get_server_id);
1321
1422
Parameters
1523
----------

‎src/libmongoc/doc/mongoc_bulk_operation_get_server_id.rst

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
:man_page: mongoc_bulk_operation_get_server_id
2+
3+
mongoc_bulk_operation_get_server_id()
4+
=====================================
5+
6+
Synopsis
7+
--------
8+
9+
.. code-block:: c
10+
11+
uint32_t
12+
mongoc_bulk_operation_get_server_id (const mongoc_bulk_operation_t *bulk);
13+
14+
Parameters
15+
----------
16+
17+
* ``bulk``: A :symbol:`mongoc_bulk_operation_t`.
18+
19+
Description
20+
-----------
21+
22+
Retrieves the opaque id of the server used for the operation.
23+
24+
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.
25+

‎src/libmongoc/doc/mongoc_bulk_operation_set_hint.rst

+9-2
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,21 @@
33
mongoc_bulk_operation_set_hint()
44
================================
55

6+
.. warning::
7+
.. deprecated:: 1.28.0
8+
9+
This function is deprecated and should not be used in new code.
10+
11+
Please use :symbol:`mongoc_bulk_operation_set_server_id()` in new code.
12+
613
Synopsis
714
--------
815

916
.. code-block:: c
1017
1118
void
12-
mongoc_bulk_operation_set_hint (const mongoc_bulk_operation_t *bulk,
13-
uint32_t server_id);
19+
mongoc_bulk_operation_set_hint (mongoc_bulk_operation_t *bulk, uint32_t server_id)
20+
BSON_GNUC_DEPRECATED_FOR (mongoc_bulk_operation_set_server_id);
1421
1522
Parameters
1623
----------

‎src/libmongoc/doc/mongoc_bulk_operation_set_server_id.rst

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
:man_page: mongoc_bulk_operation_set_server_id
2+
3+
mongoc_bulk_operation_set_server_id()
4+
=====================================
5+
6+
Synopsis
7+
--------
8+
9+
.. code-block:: c
10+
11+
void
12+
mongoc_bulk_operation_set_server_id (mongoc_bulk_operation_t *bulk, uint32_t server_id);
13+
14+
Parameters
15+
----------
16+
17+
* ``bulk``: A :symbol:`mongoc_bulk_operation_t`.
18+
* ``server_id``: An opaque id identifying the server to use.
19+
20+
Description
21+
-----------
22+
23+
Specifies which server to use for the operation. This function has an effect only if called before :symbol:`mongoc_bulk_operation_execute`.
24+
25+
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.
26+

‎src/libmongoc/doc/mongoc_bulk_operation_t.rst

+2
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ After adding all of the write operations to the :symbol:`mongoc_bulk_operation_t
4747
mongoc_bulk_operation_destroy
4848
mongoc_bulk_operation_execute
4949
mongoc_bulk_operation_get_hint
50+
mongoc_bulk_operation_get_server_id
5051
mongoc_bulk_operation_get_write_concern
5152
mongoc_bulk_operation_insert
5253
mongoc_bulk_operation_insert_with_opts
@@ -60,6 +61,7 @@ After adding all of the write operations to the :symbol:`mongoc_bulk_operation_t
6061
mongoc_bulk_operation_set_client_session
6162
mongoc_bulk_operation_set_comment
6263
mongoc_bulk_operation_set_hint
64+
mongoc_bulk_operation_set_server_id
6365
mongoc_bulk_operation_set_let
6466
mongoc_bulk_operation_update
6567
mongoc_bulk_operation_update_many_with_opts

‎src/libmongoc/doc/mongoc_cursor_get_hint.rst

+9-2
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,20 @@
33
mongoc_cursor_get_hint()
44
========================
55

6+
.. warning::
7+
.. deprecated:: 1.28.0
8+
9+
This function is deprecated and should not be used in new code.
10+
11+
Please use :symbol:`mongoc_cursor_get_server_id()` in new code.
12+
613
Synopsis
714
--------
815

916
.. code-block:: c
1017
1118
uint32_t
12-
mongoc_cursor_get_hint (const mongoc_cursor_t *cursor);
19+
mongoc_cursor_get_hint (const mongoc_cursor_t *cursor) BSON_GNUC_DEPRECATED_FOR (mongoc_cursor_get_server_id);
1320
1421
Parameters
1522
----------
@@ -23,5 +30,5 @@ Retrieves the opaque id of the server used for the operation.
2330

2431
(The function name includes the old term "hint" for the sake of backward compatibility, but we now call this number a "server id".)
2532

26-
This number is zero until the driver actually uses a server when executing the find operation or :symbol:`mongoc_cursor_set_hint` is called.
33+
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.
2734

‎src/libmongoc/doc/mongoc_cursor_get_server_id.rst

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
:man_page: mongoc_cursor_get_server_id
2+
3+
mongoc_cursor_get_server_id()
4+
=============================
5+
6+
Synopsis
7+
--------
8+
9+
.. code-block:: c
10+
11+
uint32_t
12+
mongoc_cursor_get_server_id (const mongoc_cursor_t *cursor);
13+
14+
Parameters
15+
----------
16+
17+
* ``cursor``: A :symbol:`mongoc_cursor_t`.
18+
19+
Description
20+
-----------
21+
22+
Retrieves the opaque id of the server used for the operation.
23+
24+
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.
25+

‎src/libmongoc/doc/mongoc_cursor_set_hint.rst

+9-1
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,21 @@
33
mongoc_cursor_set_hint()
44
========================
55

6+
.. warning::
7+
.. deprecated:: 1.28.0
8+
9+
This function is deprecated and should not be used in new code.
10+
11+
Please use :symbol:`mongoc_cursor_set_server_id()` in new code.
12+
613
Synopsis
714
--------
815

916
.. code-block:: c
1017
1118
bool
12-
mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id);
19+
mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id)
20+
BSON_GNUC_DEPRECATED_FOR (mongoc_cursor_set_server_id);
1321
1422
Parameters
1523
----------

‎src/libmongoc/doc/mongoc_cursor_set_server_id.rst

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
:man_page: mongoc_cursor_set_server_id
2+
3+
mongoc_cursor_set_server_id()
4+
=============================
5+
6+
Synopsis
7+
--------
8+
9+
.. code-block:: c
10+
11+
bool
12+
mongoc_cursor_set_server_id (mongoc_cursor_t *cursor, uint32_t server_id)
13+
14+
Parameters
15+
----------
16+
17+
* ``cursor``: A :symbol:`mongoc_cursor_t`.
18+
* ``server_id``: An opaque id identifying the server to use.
19+
20+
Description
21+
-----------
22+
23+
Specifies which server to use for the operation. This function has an effect only if called before the find operation is executed.
24+
25+
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.
26+
27+
Returns
28+
-------
29+
30+
Returns true on success. If any arguments are invalid, returns false and logs an error.
31+

‎src/libmongoc/doc/mongoc_cursor_t.rst

+2
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ Example
5252
mongoc_cursor_error_document
5353
mongoc_cursor_get_batch_size
5454
mongoc_cursor_get_hint
55+
mongoc_cursor_get_server_id
5556
mongoc_cursor_get_host
5657
mongoc_cursor_get_id
5758
mongoc_cursor_get_limit
@@ -63,6 +64,7 @@ Example
6364
mongoc_cursor_next
6465
mongoc_cursor_set_batch_size
6566
mongoc_cursor_set_hint
67+
mongoc_cursor_set_server_id
6668
mongoc_cursor_set_limit
6769
mongoc_cursor_set_max_await_time_ms
6870

‎src/libmongoc/src/mongoc/mongoc-bulk-operation.c

+12-1
Original file line numberDiff line numberDiff line change
@@ -913,15 +913,26 @@ mongoc_bulk_operation_set_client_session (mongoc_bulk_operation_t *bulk,
913913

914914
uint32_t
915915
mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk)
916+
{
917+
return mongoc_bulk_operation_get_server_id (bulk);
918+
}
919+
920+
uint32_t
921+
mongoc_bulk_operation_get_server_id (const mongoc_bulk_operation_t *bulk)
916922
{
917923
BSON_ASSERT_PARAM (bulk);
918924

919925
return bulk->server_id;
920926
}
921927

922-
923928
void
924929
mongoc_bulk_operation_set_hint (mongoc_bulk_operation_t *bulk, uint32_t server_id)
930+
{
931+
mongoc_bulk_operation_set_server_id (bulk, server_id);
932+
}
933+
934+
void
935+
mongoc_bulk_operation_set_server_id (mongoc_bulk_operation_t *bulk, uint32_t server_id)
925936
{
926937
BSON_ASSERT_PARAM (bulk);
927938

‎src/libmongoc/src/mongoc/mongoc-bulk-operation.h

+10-4
Original file line numberDiff line numberDiff line change
@@ -131,12 +131,18 @@ mongoc_bulk_operation_set_client (mongoc_bulk_operation_t *bulk, void *client);
131131
MONGOC_EXPORT (void)
132132
mongoc_bulk_operation_set_client_session (mongoc_bulk_operation_t *bulk,
133133
struct _mongoc_client_session_t *client_session);
134-
/* These names include the term "hint" for backward compatibility, should be
135-
* mongoc_bulk_operation_get_server_id, mongoc_bulk_operation_set_server_id. */
134+
// `mongoc_bulk_operation_set_hint` is deprecated for the more aptly named `mongoc_bulk_operation_set_server_id`.
136135
MONGOC_EXPORT (void)
137-
mongoc_bulk_operation_set_hint (mongoc_bulk_operation_t *bulk, uint32_t server_id);
136+
mongoc_bulk_operation_set_hint (mongoc_bulk_operation_t *bulk, uint32_t server_id)
137+
BSON_GNUC_DEPRECATED_FOR (mongoc_bulk_operation_set_server_id);
138+
MONGOC_EXPORT (void)
139+
mongoc_bulk_operation_set_server_id (mongoc_bulk_operation_t *bulk, uint32_t server_id);
140+
// `mongoc_bulk_operation_get_hint` is deprecated for the more aptly named `mongoc_bulk_operation_get_server_id`.
141+
MONGOC_EXPORT (uint32_t)
142+
mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk)
143+
BSON_GNUC_DEPRECATED_FOR (mongoc_bulk_operation_get_server_id);
138144
MONGOC_EXPORT (uint32_t)
139-
mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk);
145+
mongoc_bulk_operation_get_server_id (const mongoc_bulk_operation_t *bulk);
140146
MONGOC_EXPORT (const mongoc_write_concern_t *)
141147
mongoc_bulk_operation_get_write_concern (const mongoc_bulk_operation_t *bulk);
142148
BSON_END_DECLS

‎src/libmongoc/src/mongoc/mongoc-cursor.c

+15-3
Original file line numberDiff line numberDiff line change
@@ -291,7 +291,7 @@ _mongoc_cursor_new_with_opts (mongoc_client_t *client,
291291
}
292292

293293
if (server_id) {
294-
(void) mongoc_cursor_set_hint (cursor, server_id);
294+
(void) mongoc_cursor_set_server_id (cursor, server_id);
295295
}
296296

297297
// Selectively copy the options:
@@ -1437,16 +1437,22 @@ mongoc_cursor_get_limit (const mongoc_cursor_t *cursor)
14371437

14381438
bool
14391439
mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id)
1440+
{
1441+
return mongoc_cursor_set_server_id (cursor, server_id);
1442+
}
1443+
1444+
bool
1445+
mongoc_cursor_set_server_id (mongoc_cursor_t *cursor, uint32_t server_id)
14401446
{
14411447
BSON_ASSERT (cursor);
14421448

14431449
if (cursor->server_id) {
1444-
MONGOC_ERROR ("mongoc_cursor_set_hint: server_id already set");
1450+
MONGOC_ERROR ("mongoc_cursor_set_server_id: server_id already set");
14451451
return false;
14461452
}
14471453

14481454
if (!server_id) {
1449-
MONGOC_ERROR ("mongoc_cursor_set_hint: cannot set server_id to 0");
1455+
MONGOC_ERROR ("mongoc_cursor_set_server_id: cannot set server_id to 0");
14501456
return false;
14511457
}
14521458

@@ -1458,6 +1464,12 @@ mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id)
14581464

14591465
uint32_t
14601466
mongoc_cursor_get_hint (const mongoc_cursor_t *cursor)
1467+
{
1468+
return mongoc_cursor_get_server_id (cursor);
1469+
}
1470+
1471+
uint32_t
1472+
mongoc_cursor_get_server_id (const mongoc_cursor_t *cursor)
14611473
{
14621474
BSON_ASSERT (cursor);
14631475

‎src/libmongoc/src/mongoc/mongoc-cursor.h

+9-4
Original file line numberDiff line numberDiff line change
@@ -59,12 +59,17 @@ MONGOC_EXPORT (bool)
5959
mongoc_cursor_set_limit (mongoc_cursor_t *cursor, int64_t limit);
6060
MONGOC_EXPORT (int64_t)
6161
mongoc_cursor_get_limit (const mongoc_cursor_t *cursor);
62-
/* These names include the term "hint" for backward compatibility, should be
63-
* mongoc_cursor_get_server_id, mongoc_cursor_set_server_id. */
62+
// `mongoc_cursor_set_hint` is deprecated for more aptly named `mongoc_cursor_set_server_id`.
6463
MONGOC_EXPORT (bool)
65-
mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id);
64+
mongoc_cursor_set_hint (mongoc_cursor_t *cursor, uint32_t server_id)
65+
BSON_GNUC_DEPRECATED_FOR (mongoc_cursor_set_server_id);
66+
MONGOC_EXPORT (bool)
67+
mongoc_cursor_set_server_id (mongoc_cursor_t *cursor, uint32_t server_id);
68+
// `mongoc_cursor_get_hint` is deprecated for more aptly named `mongoc_cursor_get_server_id`.
69+
MONGOC_EXPORT (uint32_t)
70+
mongoc_cursor_get_hint (const mongoc_cursor_t *cursor) BSON_GNUC_DEPRECATED_FOR (mongoc_cursor_get_server_id);
6671
MONGOC_EXPORT (uint32_t)
67-
mongoc_cursor_get_hint (const mongoc_cursor_t *cursor);
72+
mongoc_cursor_get_server_id (const mongoc_cursor_t *cursor);
6873
MONGOC_EXPORT (int64_t)
6974
mongoc_cursor_get_id (const mongoc_cursor_t *cursor);
7075
MONGOC_EXPORT (void)

0 commit comments

Comments
 (0)