Skip to content

Commit d6f975d

Browse files
vector-of-boolvector-of-bool
authored
[CDRIVER-5916] Deprecate the Hedged-Reads APIs (#1889)
* Tweak definition of deprecation macros. We now emit deprecation warnings on MSVC as well, and all deprecation warnings now include a string message, if possible. * Update existing deprecation attributes and formatting - Replace use of `BSON_GNUC_DEPRECATED...` with `BSON_DEPRECATED...` - Reformat attribute macros as attributes according to clang-format. - Give dense API listings in public headers some breathing room. * A macro to disable deprecation warnings with _Pragma * Annotate and document "hedge" APIs as deprecated
1 parent 9b19be9 commit d6f975d

31 files changed

+861
-403
lines changed

‎.clang-format

+3
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,9 @@ AlwaysBreakBeforeMultilineStrings: false
5353
AlwaysBreakTemplateDeclarations: MultiLine
5454
AttributeMacros:
5555
- __capability
56+
- BSON_GNUC_WARN_UNUSED_RESULT
57+
- BSON_DEPRECATED
58+
- BSON_DEPRECATED_FOR
5659
BinPackArguments: false
5760
BinPackParameters: false
5861
BitFieldColonSpacing: Both

‎src/common/src/mlib/config.h

+7
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,13 @@
291291
#define _mlibTestBuildConfig_RelWithDebInfo_RelWithDebInfo()
292292
#define _mlibTestBuildConfig_MinSizeRel_MinSizeRel()
293293

294+
/**
295+
* @brief Emit a _Pragma that will disable warnings about the use of deprecated entities.
296+
*/
297+
#define mlib_disable_deprecation_warnings() \
298+
mlib_gnu_warning_disable ("-Wdeprecated-declarations"); \
299+
mlib_msvc_warning (disable : 4996)
300+
294301
/**
295302
* @brief Function-like macro that expands to `1` if we are certain that we are
296303
* compiling with optimizations enabled.

‎src/libbson/src/bson/bson-atomic.h

+92-80
Large diffs are not rendered by default.

‎src/libbson/src/bson/bson-cmp.h

+48-37
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@
3939
#define BSON_BEGIN_IGNORE_DEPRECATIONS \
4040
_Pragma ("clang diagnostic push") _Pragma ("clang diagnostic ignored \"-Wdeprecated-declarations\"")
4141
#define BSON_END_IGNORE_DEPRECATIONS _Pragma ("clang diagnostic pop")
42+
#elif defined(_MSC_VER)
43+
#define BSON_BEGIN_IGNORE_DEPRECATIONS __pragma (warning (push)) __pragma (warning (disable : 4996))
44+
#define BSON_END_IGNORE_DEPRECATIONS __pragma (warning (pop))
4245
#else
4346
#define BSON_BEGIN_IGNORE_DEPRECATIONS
4447
#define BSON_END_IGNORE_DEPRECATIONS
@@ -70,25 +73,29 @@ BSON_BEGIN_DECLS
7073
* recommended.
7174
*/
7275

73-
#define BSON_CMP_SET(op, ss, uu, su, us) \
74-
static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_cmp_, op, _ss) (int64_t t, int64_t u) \
75-
{ \
76-
return (ss); \
77-
} \
78-
\
79-
static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_cmp_, op, _uu) (uint64_t t, uint64_t u) \
80-
{ \
81-
return (uu); \
82-
} \
83-
\
84-
static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_cmp_, op, _su) (int64_t t, uint64_t u) \
85-
{ \
86-
return (su); \
87-
} \
88-
\
89-
static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_cmp_, op, _us) (uint64_t t, int64_t u) \
90-
{ \
91-
return (us); \
76+
#define BSON_CMP_SET(op, ss, uu, su, us) \
77+
static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
78+
bson_cmp_, op, _ss) (int64_t t, int64_t u) \
79+
{ \
80+
return (ss); \
81+
} \
82+
\
83+
static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
84+
bson_cmp_, op, _uu) (uint64_t t, uint64_t u) \
85+
{ \
86+
return (uu); \
87+
} \
88+
\
89+
static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
90+
bson_cmp_, op, _su) (int64_t t, uint64_t u) \
91+
{ \
92+
return (su); \
93+
} \
94+
\
95+
static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
96+
bson_cmp_, op, _us) (uint64_t t, int64_t u) \
97+
{ \
98+
return (us); \
9299
}
93100

94101
BSON_CMP_SET (equal, t == u, t == u, t < 0 ? false : (uint64_t) (t) == u, u < 0 ? false : t == (uint64_t) (u))
@@ -121,28 +128,32 @@ BSON_CMP_SET (greater_equal,
121128

122129
/* Return true if the given value is within the range of the corresponding
123130
* signed type. The suffix must match the signedness of the given value. */
124-
#define BSON_IN_RANGE_SET_SIGNED(Type, min, max) \
125-
static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_in_range, _##Type, _signed) (int64_t value) \
126-
{ \
127-
return bson_cmp_greater_equal_ss (value, min) && bson_cmp_less_equal_ss (value, max); \
128-
} \
129-
\
130-
static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_in_range, _##Type, _unsigned) (uint64_t value) \
131-
{ \
132-
return bson_cmp_greater_equal_us (value, min) && bson_cmp_less_equal_us (value, max); \
131+
#define BSON_IN_RANGE_SET_SIGNED(Type, min, max) \
132+
static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
133+
bson_in_range, _##Type, _signed) (int64_t value) \
134+
{ \
135+
return bson_cmp_greater_equal_ss (value, min) && bson_cmp_less_equal_ss (value, max); \
136+
} \
137+
\
138+
static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
139+
bson_in_range, _##Type, _unsigned) (uint64_t value) \
140+
{ \
141+
return bson_cmp_greater_equal_us (value, min) && bson_cmp_less_equal_us (value, max); \
133142
}
134143

135144
/* Return true if the given value is within the range of the corresponding
136145
* unsigned type. The suffix must match the signedness of the given value. */
137-
#define BSON_IN_RANGE_SET_UNSIGNED(Type, max) \
138-
static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_in_range, _##Type, _signed) (int64_t value) \
139-
{ \
140-
return bson_cmp_greater_equal_su (value, 0u) && bson_cmp_less_equal_su (value, max); \
141-
} \
142-
\
143-
static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_in_range, _##Type, _unsigned) (uint64_t value) \
144-
{ \
145-
return bson_cmp_less_equal_uu (value, max); \
146+
#define BSON_IN_RANGE_SET_UNSIGNED(Type, max) \
147+
static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
148+
bson_in_range, _##Type, _signed) (int64_t value) \
149+
{ \
150+
return bson_cmp_greater_equal_su (value, 0u) && bson_cmp_less_equal_su (value, max); \
151+
} \
152+
\
153+
static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
154+
bson_in_range, _##Type, _unsigned) (uint64_t value) \
155+
{ \
156+
return bson_cmp_less_equal_uu (value, max); \
146157
}
147158

148159
BSON_IN_RANGE_SET_SIGNED (signed_char, SCHAR_MIN, SCHAR_MAX)

‎src/libbson/src/bson/bson-macros.h

+24-8
Original file line numberDiff line numberDiff line change
@@ -329,23 +329,39 @@ _bson_assert_failed_on_param (const char *param, const char *func)
329329
#define BSON_TYPEOF typeof
330330
#endif
331331

332+
/**
333+
* @brief Statically annotate an entity as deprecated, including the given deprecation message
334+
*
335+
* @param Message The message to be included in a deprecation warning. This
336+
* should be a string literal.
337+
*/
338+
#define BSON_DEPRECATED(Message) _bsonDeprecatedImpl (Message)
332339

333-
#if BSON_GNUC_CHECK_VERSION(3, 1)
334-
#define BSON_GNUC_DEPRECATED __attribute__ ((__deprecated__))
340+
// Pick the appropriate implementation of a deprecation attribute
341+
#if defined(_MSC_VER)
342+
// For MSVC, emit __declspec(deprecated(Msg))
343+
#define _bsonDeprecatedImpl(Msg) __declspec (deprecated (Msg))
344+
#elif defined(__GNUC__) && (defined(__clang__) || BSON_GNUC_CHECK_VERSION(4, 5))
345+
// For new enough Clang and GCC, emit __attribute__((__deprecated__(Msg)))
346+
#define _bsonDeprecatedImpl(Msg) __attribute__ ((__deprecated__ (Msg)))
347+
#elif defined(__GNUC__)
348+
// For older GCC, emit deprecation attribute without the message
349+
#define _bsonDeprecatedImpl(Msg) __attribute__ ((__deprecated__))
335350
#else
336-
#define BSON_GNUC_DEPRECATED
351+
// For other compilers, emit nothing
352+
#define _bsonDeprecatedImpl(Msg)
337353
#endif
338354

355+
#define BSON_DEPRECATED_FOR(F) BSON_DEPRECATED ("This API is deprecated. Use " #F " instead.")
356+
357+
#define BSON_GNUC_DEPRECATED BSON_DEPRECATED ("This API is deprecated")
358+
#define BSON_GNUC_DEPRECATED_FOR(F) BSON_DEPRECATED_FOR (F)
359+
339360
#define BSON_CONCAT_IMPL(a, ...) a##__VA_ARGS__
340361
#define BSON_CONCAT(a, ...) BSON_CONCAT_IMPL (a, __VA_ARGS__)
341362
#define BSON_CONCAT3(a, b, c) BSON_CONCAT (a, BSON_CONCAT (b, c))
342363
#define BSON_CONCAT4(a, b, c, d) BSON_CONCAT (BSON_CONCAT (a, b), BSON_CONCAT (c, d))
343364

344-
#if BSON_GNUC_CHECK_VERSION(4, 5)
345-
#define BSON_GNUC_DEPRECATED_FOR(f) __attribute__ ((deprecated ("Use " #f " instead")))
346-
#else
347-
#define BSON_GNUC_DEPRECATED_FOR(f) BSON_GNUC_DEPRECATED
348-
#endif
349365

350366
/**
351367
* @brief String-ify the given argument

‎src/libbson/src/bson/bson-md5.h

+7-6
Original file line numberDiff line numberDiff line change
@@ -73,12 +73,13 @@ typedef struct {
7373
} bson_md5_t;
7474

7575

76-
BSON_EXPORT (void)
77-
bson_md5_init (bson_md5_t *pms) BSON_GNUC_DEPRECATED;
78-
BSON_EXPORT (void)
79-
bson_md5_append (bson_md5_t *pms, const uint8_t *data, uint32_t nbytes) BSON_GNUC_DEPRECATED;
80-
BSON_EXPORT (void)
81-
bson_md5_finish (bson_md5_t *pms, uint8_t digest[16]) BSON_GNUC_DEPRECATED;
76+
BSON_DEPRECATED ("<bson/bson-md5.h> APIs are deprecated") BSON_EXPORT (void) bson_md5_init (bson_md5_t *pms);
77+
78+
BSON_DEPRECATED ("<bson/bson-md5.h> APIs are deprecated")
79+
BSON_EXPORT (void) bson_md5_append (bson_md5_t *pms, const uint8_t *data, uint32_t nbytes);
80+
81+
BSON_DEPRECATED ("<bson/bson-md5.h> APIs are deprecated")
82+
BSON_EXPORT (void) bson_md5_finish (bson_md5_t *pms, uint8_t digest[16]);
8283

8384

8485
BSON_END_DECLS

‎src/libbson/src/bson/bson-oid.h

+2-2
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,8 @@ BSON_EXPORT (void)
5050
bson_oid_init_from_data (bson_oid_t *oid, const uint8_t *data);
5151
BSON_EXPORT (void)
5252
bson_oid_init_from_string (bson_oid_t *oid, const char *str);
53-
BSON_EXPORT (void)
54-
bson_oid_init_sequence (bson_oid_t *oid, bson_context_t *context) BSON_GNUC_DEPRECATED_FOR (bson_oid_init);
53+
BSON_DEPRECATED_FOR (bson_oid_init)
54+
BSON_EXPORT (void) bson_oid_init_sequence (bson_oid_t *oid, bson_context_t *context);
5555
BSON_EXPORT (void)
5656
bson_oid_to_string (const bson_oid_t *oid, char str[25]);
5757

‎src/libbson/src/bson/bson-string.h

+31-14
Original file line numberDiff line numberDiff line change
@@ -37,42 +37,59 @@ typedef struct {
3737
} bson_string_t;
3838

3939

40-
BSON_EXPORT (bson_string_t *)
41-
bson_string_new (const char *str) BSON_GNUC_DEPRECATED;
42-
BSON_EXPORT (char *)
43-
bson_string_free (bson_string_t *string, bool free_segment) BSON_GNUC_DEPRECATED;
44-
BSON_EXPORT (void)
45-
bson_string_append (bson_string_t *string, const char *str) BSON_GNUC_DEPRECATED;
46-
BSON_EXPORT (void)
47-
bson_string_append_c (bson_string_t *string, char str) BSON_GNUC_DEPRECATED;
48-
BSON_EXPORT (void)
49-
bson_string_append_unichar (bson_string_t *string, bson_unichar_t unichar) BSON_GNUC_DEPRECATED;
50-
BSON_EXPORT (void)
51-
bson_string_append_printf (bson_string_t *string, const char *format, ...) BSON_GNUC_PRINTF (2, 3) BSON_GNUC_DEPRECATED;
52-
BSON_EXPORT (void)
53-
bson_string_truncate (bson_string_t *string, uint32_t len) BSON_GNUC_DEPRECATED;
40+
BSON_DEPRECATED ("bson_string_t APIs are deprecated") BSON_EXPORT (bson_string_t *) bson_string_new (const char *str);
41+
42+
BSON_DEPRECATED ("bson_string_t APIs are deprecated")
43+
BSON_EXPORT (char *) bson_string_free (bson_string_t *string, bool free_segment);
44+
45+
BSON_DEPRECATED ("bson_string_t APIs are deprecated")
46+
BSON_EXPORT (void) bson_string_append (bson_string_t *string, const char *str);
47+
48+
BSON_DEPRECATED ("bson_string_t APIs are deprecated")
49+
BSON_EXPORT (void) bson_string_append_c (bson_string_t *string, char str);
50+
51+
BSON_DEPRECATED ("bson_string_t APIs are deprecated")
52+
BSON_EXPORT (void) bson_string_append_unichar (bson_string_t *string, bson_unichar_t unichar);
53+
54+
BSON_DEPRECATED ("bson_string_t APIs are deprecated")
55+
BSON_EXPORT (void) bson_string_append_printf (bson_string_t *string, const char *format, ...) BSON_GNUC_PRINTF (2, 3);
56+
57+
BSON_DEPRECATED ("bson_string_t APIs are deprecated")
58+
BSON_EXPORT (void) bson_string_truncate (bson_string_t *string, uint32_t len);
59+
5460
BSON_EXPORT (char *)
5561
bson_strdup (const char *str);
62+
5663
BSON_EXPORT (char *)
5764
bson_strdup_printf (const char *format, ...) BSON_GNUC_PRINTF (1, 2);
65+
5866
BSON_EXPORT (char *)
5967
bson_strdupv_printf (const char *format, va_list args) BSON_GNUC_PRINTF (1, 0);
68+
6069
BSON_EXPORT (char *)
6170
bson_strndup (const char *str, size_t n_bytes);
71+
6272
BSON_EXPORT (void)
6373
bson_strncpy (char *dst, const char *src, size_t size);
74+
6475
BSON_EXPORT (int)
6576
bson_vsnprintf (char *str, size_t size, const char *format, va_list ap) BSON_GNUC_PRINTF (3, 0);
77+
6678
BSON_EXPORT (int)
6779
bson_snprintf (char *str, size_t size, const char *format, ...) BSON_GNUC_PRINTF (3, 4);
80+
6881
BSON_EXPORT (void)
6982
bson_strfreev (char **strv);
83+
7084
BSON_EXPORT (size_t)
7185
bson_strnlen (const char *s, size_t maxlen);
86+
7287
BSON_EXPORT (int64_t)
7388
bson_ascii_strtoll (const char *str, char **endptr, int base);
89+
7490
BSON_EXPORT (int)
7591
bson_strcasecmp (const char *s1, const char *s2);
92+
7693
BSON_EXPORT (bool)
7794
bson_isspace (int c);
7895

‎src/libbson/src/bson/bson.h

+6-6
Original file line numberDiff line numberDiff line change
@@ -302,9 +302,9 @@ bson_copy_to (const bson_t *src, bson_t *dst);
302302
* more fields in a bson_t. Note that bson_init() will be called
303303
* on dst.
304304
*/
305+
BSON_DEPRECATED_FOR (bson_copy_to_excluding_noinit)
305306
BSON_EXPORT (void)
306-
bson_copy_to_excluding (const bson_t *src, bson_t *dst, const char *first_exclude, ...) BSON_GNUC_NULL_TERMINATED
307-
BSON_GNUC_DEPRECATED_FOR (bson_copy_to_excluding_noinit);
307+
bson_copy_to_excluding (const bson_t *src, bson_t *dst, const char *first_exclude, ...) BSON_GNUC_NULL_TERMINATED;
308308

309309
/**
310310
* bson_copy_to_excluding_noinit:
@@ -531,8 +531,8 @@ bson_as_canonical_extended_json (const bson_t *bson, size_t *length);
531531
*
532532
* Returns: A newly allocated string that should be freed with bson_free().
533533
*/
534-
BSON_EXPORT (char *)
535-
bson_as_json (const bson_t *bson, size_t *length) BSON_GNUC_DEPRECATED_FOR (bson_as_legacy_extended_json);
534+
BSON_DEPRECATED_FOR (bson_as_legacy_extended_json)
535+
BSON_EXPORT (char *) bson_as_json (const bson_t *bson, size_t *length);
536536

537537
// `bson_as_legacy_extended_json` is a non-deprecated form of `bson_as_json`.
538538
BSON_EXPORT (char *)
@@ -562,8 +562,8 @@ bson_as_relaxed_extended_json (const bson_t *bson, size_t *length);
562562

563563

564564
/* like bson_as_json() but for outermost arrays. */
565-
BSON_EXPORT (char *)
566-
bson_array_as_json (const bson_t *bson, size_t *length) BSON_GNUC_DEPRECATED_FOR (bson_array_as_legacy_extended_json);
565+
BSON_DEPRECATED_FOR (bson_array_as_legacy_extended_json)
566+
BSON_EXPORT (char *) bson_array_as_json (const bson_t *bson, size_t *length);
567567

568568
// `bson_array_as_legacy_extended_json` is a non-deprecated form of `bson_array_as_json`.
569569
BSON_EXPORT (char *)

‎src/libmongoc/doc/mongoc_read_prefs_get_hedge.rst

+5
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@
33
mongoc_read_prefs_get_hedge()
44
=============================
55

6+
.. deprecated:: MongoDB Server 8.0
7+
8+
Hedged reads are deprecated in MongoDB version 8.0 and will be removed in
9+
a future release.
10+
611
Synopsis
712
--------
813

‎src/libmongoc/doc/mongoc_read_prefs_set_hedge.rst

+5
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@
33
mongoc_read_prefs_set_hedge()
44
=============================
55

6+
.. deprecated:: MongoDB Server 8.0
7+
8+
Hedged reads are deprecated in MongoDB version 8.0 and will be removed in
9+
a future release.
10+
611
Synopsis
712
--------
813

‎src/libmongoc/doc/mongoc_read_prefs_t.rst

+12-2
Original file line numberDiff line numberDiff line change
@@ -70,9 +70,19 @@ Max Staleness is also supported by sharded clusters of replica sets if all serve
7070
Hedged Reads
7171
------------
7272

73-
When connecting to a sharded cluster running MongoDB 4.4 or later, reads can be sent in parallel to the two "best" hosts. Once one result returns, any other outstanding operations that were part of the hedged read are cancelled.
73+
.. deprecated:: MongoDB Server 8.0
7474

75-
When the read preference mode is ``MONGOC_READ_NEAREST`` and the sharded cluster is running MongoDB 4.4 or later, hedged reads are enabled by default. Additionally, hedged reads may be explicitly enabled or disabled by calling :symbol:`mongoc_read_prefs_set_hedge` with a BSON document, e.g.
75+
Hedged reads are deprecated in MongoDB version 8.0 and will be removed in
76+
a future release.
77+
78+
When connecting to a sharded cluster running MongoDB 4.4 or later, reads can be
79+
sent in parallel to the two "best" hosts. Once one result returns, any other
80+
outstanding operations that were part of the hedged read are cancelled.
81+
82+
When the read preference mode is ``MONGOC_READ_NEAREST`` and the sharded cluster
83+
is running MongoDB 4.4 or later, hedged reads are enabled by default.
84+
Additionally, hedged reads may be explicitly enabled or disabled by calling
85+
:symbol:`mongoc_read_prefs_set_hedge` with a BSON document, e.g.
7686

7787
.. code-block:: none
7888

0 commit comments

Comments
 (0)