[CDRIVER-5916] Deprecate the Hedged-Reads APIs

.clang-format

@@ -53,6 +53,9 @@ AlwaysBreakBeforeMultilineStrings: false
 AlwaysBreakTemplateDeclarations: MultiLine
 AttributeMacros:
   - __capability
+  - BSON_GNUC_WARN_UNUSED_RESULT
+  - BSON_DEPRECATED
+  - BSON_DEPRECATED_FOR
 BinPackArguments: false
 BinPackParameters: false
 BitFieldColonSpacing: Both

src/common/src/mlib/config.h

@@ -291,6 +291,13 @@
 #define _mlibTestBuildConfig_RelWithDebInfo_RelWithDebInfo()
 #define _mlibTestBuildConfig_MinSizeRel_MinSizeRel()
 
+/**
+ * @brief Emit a _Pragma that will disable warnings about the use of deprecated entities.
+ */
+#define mlib_disable_deprecation_warnings()                \
+   mlib_gnu_warning_disable ("-Wdeprecated-declarations"); \
+   mlib_msvc_warning (disable : 4996)
+
 /**
  * @brief Function-like macro that expands to `1` if we are certain that we are
  * compiling with optimizations enabled.

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

@@ -39,6 +39,9 @@
 #define BSON_BEGIN_IGNORE_DEPRECATIONS \
    _Pragma ("clang diagnostic push") _Pragma ("clang diagnostic ignored \"-Wdeprecated-declarations\"")
 #define BSON_END_IGNORE_DEPRECATIONS _Pragma ("clang diagnostic pop")
+#elif defined(_MSC_VER)
+#define BSON_BEGIN_IGNORE_DEPRECATIONS __pragma (warning (push)) __pragma (warning (disable : 4996))
+#define BSON_END_IGNORE_DEPRECATIONS __pragma (warning (pop))
 #else
 #define BSON_BEGIN_IGNORE_DEPRECATIONS
 #define BSON_END_IGNORE_DEPRECATIONS
@@ -70,25 +73,29 @@ BSON_BEGIN_DECLS
  * recommended.
  */
 
-#define BSON_CMP_SET(op, ss, uu, su, us)                                                                   \
-   static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_cmp_, op, _ss) (int64_t t, int64_t u)   \
-   {                                                                                                       \
-      return (ss);                                                                                         \
-   }                                                                                                       \
-                                                                                                           \
-   static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_cmp_, op, _uu) (uint64_t t, uint64_t u) \
-   {                                                                                                       \
-      return (uu);                                                                                         \
-   }                                                                                                       \
-                                                                                                           \
-   static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_cmp_, op, _su) (int64_t t, uint64_t u)  \
-   {                                                                                                       \
-      return (su);                                                                                         \
-   }                                                                                                       \
-                                                                                                           \
-   static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_cmp_, op, _us) (uint64_t t, int64_t u)  \
-   {                                                                                                       \
-      return (us);                                                                                         \
+#define BSON_CMP_SET(op, ss, uu, su, us)                                                            \
+   static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
+      bson_cmp_, op, _ss) (int64_t t, int64_t u)                                                    \
+   {                                                                                                \
+      return (ss);                                                                                  \
+   }                                                                                                \
+                                                                                                    \
+   static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
+      bson_cmp_, op, _uu) (uint64_t t, uint64_t u)                                                  \
+   {                                                                                                \
+      return (uu);                                                                                  \
+   }                                                                                                \
+                                                                                                    \
+   static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
+      bson_cmp_, op, _su) (int64_t t, uint64_t u)                                                   \
+   {                                                                                                \
+      return (su);                                                                                  \
+   }                                                                                                \
+                                                                                                    \
+   static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
+      bson_cmp_, op, _us) (uint64_t t, int64_t u)                                                   \
+   {                                                                                                \
+      return (us);                                                                                  \
    }
 
 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,
 
 /* Return true if the given value is within the range of the corresponding
  * signed type. The suffix must match the signedness of the given value. */
-#define BSON_IN_RANGE_SET_SIGNED(Type, min, max)                                                                  \
-   static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_in_range, _##Type, _signed) (int64_t value)    \
-   {                                                                                                              \
-      return bson_cmp_greater_equal_ss (value, min) && bson_cmp_less_equal_ss (value, max);                       \
-   }                                                                                                              \
-                                                                                                                  \
-   static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_in_range, _##Type, _unsigned) (uint64_t value) \
-   {                                                                                                              \
-      return bson_cmp_greater_equal_us (value, min) && bson_cmp_less_equal_us (value, max);                       \
+#define BSON_IN_RANGE_SET_SIGNED(Type, min, max)                                                    \
+   static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
+      bson_in_range, _##Type, _signed) (int64_t value)                                              \
+   {                                                                                                \
+      return bson_cmp_greater_equal_ss (value, min) && bson_cmp_less_equal_ss (value, max);         \
+   }                                                                                                \
+                                                                                                    \
+   static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
+      bson_in_range, _##Type, _unsigned) (uint64_t value)                                           \
+   {                                                                                                \
+      return bson_cmp_greater_equal_us (value, min) && bson_cmp_less_equal_us (value, max);         \
    }
 
 /* Return true if the given value is within the range of the corresponding
  * unsigned type. The suffix must match the signedness of the given value. */
-#define BSON_IN_RANGE_SET_UNSIGNED(Type, max)                                                                     \
-   static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_in_range, _##Type, _signed) (int64_t value)    \
-   {                                                                                                              \
-      return bson_cmp_greater_equal_su (value, 0u) && bson_cmp_less_equal_su (value, max);                        \
-   }                                                                                                              \
-                                                                                                                  \
-   static BSON_INLINE bool BSON_GNUC_DEPRECATED BSON_CONCAT3 (bson_in_range, _##Type, _unsigned) (uint64_t value) \
-   {                                                                                                              \
-      return bson_cmp_less_equal_uu (value, max);                                                                 \
+#define BSON_IN_RANGE_SET_UNSIGNED(Type, max)                                                       \
+   static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
+      bson_in_range, _##Type, _signed) (int64_t value)                                              \
+   {                                                                                                \
+      return bson_cmp_greater_equal_su (value, 0u) && bson_cmp_less_equal_su (value, max);          \
+   }                                                                                                \
+                                                                                                    \
+   static BSON_INLINE BSON_DEPRECATED ("<bson/bson-cmp.h> APIs are deprecated") bool BSON_CONCAT3 ( \
+      bson_in_range, _##Type, _unsigned) (uint64_t value)                                           \
+   {                                                                                                \
+      return bson_cmp_less_equal_uu (value, max);                                                   \
    }
 
 BSON_IN_RANGE_SET_SIGNED (signed_char, SCHAR_MIN, SCHAR_MAX)

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

@@ -329,23 +329,39 @@ _bson_assert_failed_on_param (const char *param, const char *func)
 #define BSON_TYPEOF typeof
 #endif
 
+/**
+ * @brief Statically annotate an entity as deprecated, including the given deprecation message
+ *
+ * @param Message The message to be included in a deprecation warning. This
+ * should be a string literal.
+ */
+#define BSON_DEPRECATED(Message) _bsonDeprecatedImpl (Message)
 
-#if BSON_GNUC_CHECK_VERSION(3, 1)
-#define BSON_GNUC_DEPRECATED __attribute__ ((__deprecated__))
+// Pick the appropriate implementation of a deprecation attribute
+#if defined(_MSC_VER)
+// For MSVC, emit __declspec(deprecated(Msg))
+#define _bsonDeprecatedImpl(Msg) __declspec (deprecated (Msg))
+#elif defined(__GNUC__) && (defined(__clang__) || BSON_GNUC_CHECK_VERSION(4, 5))
+// For new enough Clang and GCC, emit __attribute__((__deprecated__(Msg)))
+#define _bsonDeprecatedImpl(Msg) __attribute__ ((__deprecated__ (Msg)))
+#elif defined(__GNUC__)
+// For older GCC, emit deprecation attribute without the message
+#define _bsonDeprecatedImpl(Msg) __attribute__ ((__deprecated__))
 #else
-#define BSON_GNUC_DEPRECATED
+// For other compilers, emit nothing
+#define _bsonDeprecatedImpl(Msg)
 #endif
 
+#define BSON_DEPRECATED_FOR(F) BSON_DEPRECATED ("This API is deprecated. Use " #F " instead.")
+
+#define BSON_GNUC_DEPRECATED BSON_DEPRECATED ("This API is deprecated")
+#define BSON_GNUC_DEPRECATED_FOR(F) BSON_DEPRECATED_FOR (F)
+
 #define BSON_CONCAT_IMPL(a, ...) a##__VA_ARGS__
 #define BSON_CONCAT(a, ...) BSON_CONCAT_IMPL (a, __VA_ARGS__)
 #define BSON_CONCAT3(a, b, c) BSON_CONCAT (a, BSON_CONCAT (b, c))
 #define BSON_CONCAT4(a, b, c, d) BSON_CONCAT (BSON_CONCAT (a, b), BSON_CONCAT (c, d))
 
-#if BSON_GNUC_CHECK_VERSION(4, 5)
-#define BSON_GNUC_DEPRECATED_FOR(f) __attribute__ ((deprecated ("Use " #f " instead")))
-#else
-#define BSON_GNUC_DEPRECATED_FOR(f) BSON_GNUC_DEPRECATED
-#endif
 
 /**
  * @brief String-ify the given argument

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

@@ -73,12 +73,13 @@ typedef struct {
 } bson_md5_t;
 
 
-BSON_EXPORT (void)
-bson_md5_init (bson_md5_t *pms) BSON_GNUC_DEPRECATED;
-BSON_EXPORT (void)
-bson_md5_append (bson_md5_t *pms, const uint8_t *data, uint32_t nbytes) BSON_GNUC_DEPRECATED;
-BSON_EXPORT (void)
-bson_md5_finish (bson_md5_t *pms, uint8_t digest[16]) BSON_GNUC_DEPRECATED;
+BSON_DEPRECATED ("<bson/bson-md5.h> APIs are deprecated") BSON_EXPORT (void) bson_md5_init (bson_md5_t *pms);
+
+BSON_DEPRECATED ("<bson/bson-md5.h> APIs are deprecated")
+BSON_EXPORT (void) bson_md5_append (bson_md5_t *pms, const uint8_t *data, uint32_t nbytes);
+
+BSON_DEPRECATED ("<bson/bson-md5.h> APIs are deprecated")
+BSON_EXPORT (void) bson_md5_finish (bson_md5_t *pms, uint8_t digest[16]);
 
 
 BSON_END_DECLS

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

@@ -50,8 +50,8 @@ BSON_EXPORT (void)
 bson_oid_init_from_data (bson_oid_t *oid, const uint8_t *data);
 BSON_EXPORT (void)
 bson_oid_init_from_string (bson_oid_t *oid, const char *str);
-BSON_EXPORT (void)
-bson_oid_init_sequence (bson_oid_t *oid, bson_context_t *context) BSON_GNUC_DEPRECATED_FOR (bson_oid_init);
+BSON_DEPRECATED_FOR (bson_oid_init)
+BSON_EXPORT (void) bson_oid_init_sequence (bson_oid_t *oid, bson_context_t *context);
 BSON_EXPORT (void)
 bson_oid_to_string (const bson_oid_t *oid, char str[25]);
 

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

@@ -37,42 +37,59 @@ typedef struct {
 } bson_string_t;
 
 
-BSON_EXPORT (bson_string_t *)
-bson_string_new (const char *str) BSON_GNUC_DEPRECATED;
-BSON_EXPORT (char *)
-bson_string_free (bson_string_t *string, bool free_segment) BSON_GNUC_DEPRECATED;
-BSON_EXPORT (void)
-bson_string_append (bson_string_t *string, const char *str) BSON_GNUC_DEPRECATED;
-BSON_EXPORT (void)
-bson_string_append_c (bson_string_t *string, char str) BSON_GNUC_DEPRECATED;
-BSON_EXPORT (void)
-bson_string_append_unichar (bson_string_t *string, bson_unichar_t unichar) BSON_GNUC_DEPRECATED;
-BSON_EXPORT (void)
-bson_string_append_printf (bson_string_t *string, const char *format, ...) BSON_GNUC_PRINTF (2, 3) BSON_GNUC_DEPRECATED;
-BSON_EXPORT (void)
-bson_string_truncate (bson_string_t *string, uint32_t len) BSON_GNUC_DEPRECATED;
+BSON_DEPRECATED ("bson_string_t APIs are deprecated") BSON_EXPORT (bson_string_t *) bson_string_new (const char *str);
+
+BSON_DEPRECATED ("bson_string_t APIs are deprecated")
+BSON_EXPORT (char *) bson_string_free (bson_string_t *string, bool free_segment);
+
+BSON_DEPRECATED ("bson_string_t APIs are deprecated")
+BSON_EXPORT (void) bson_string_append (bson_string_t *string, const char *str);
+
+BSON_DEPRECATED ("bson_string_t APIs are deprecated")
+BSON_EXPORT (void) bson_string_append_c (bson_string_t *string, char str);
+
+BSON_DEPRECATED ("bson_string_t APIs are deprecated")
+BSON_EXPORT (void) bson_string_append_unichar (bson_string_t *string, bson_unichar_t unichar);
+
+BSON_DEPRECATED ("bson_string_t APIs are deprecated")
+BSON_EXPORT (void) bson_string_append_printf (bson_string_t *string, const char *format, ...) BSON_GNUC_PRINTF (2, 3);
+
+BSON_DEPRECATED ("bson_string_t APIs are deprecated")
+BSON_EXPORT (void) bson_string_truncate (bson_string_t *string, uint32_t len);
+
 BSON_EXPORT (char *)
 bson_strdup (const char *str);
+
 BSON_EXPORT (char *)
 bson_strdup_printf (const char *format, ...) BSON_GNUC_PRINTF (1, 2);
+
 BSON_EXPORT (char *)
 bson_strdupv_printf (const char *format, va_list args) BSON_GNUC_PRINTF (1, 0);
+
 BSON_EXPORT (char *)
 bson_strndup (const char *str, size_t n_bytes);
+
 BSON_EXPORT (void)
 bson_strncpy (char *dst, const char *src, size_t size);
+
 BSON_EXPORT (int)
 bson_vsnprintf (char *str, size_t size, const char *format, va_list ap) BSON_GNUC_PRINTF (3, 0);
+
 BSON_EXPORT (int)
 bson_snprintf (char *str, size_t size, const char *format, ...) BSON_GNUC_PRINTF (3, 4);
+
 BSON_EXPORT (void)
 bson_strfreev (char **strv);
+
 BSON_EXPORT (size_t)
 bson_strnlen (const char *s, size_t maxlen);
+
 BSON_EXPORT (int64_t)
 bson_ascii_strtoll (const char *str, char **endptr, int base);
+
 BSON_EXPORT (int)
 bson_strcasecmp (const char *s1, const char *s2);
+
 BSON_EXPORT (bool)
 bson_isspace (int c);
 

src/libbson/src/bson/bson.h

@@ -302,9 +302,9 @@ bson_copy_to (const bson_t *src, bson_t *dst);
  * more fields in a bson_t. Note that bson_init() will be called
  * on dst.
  */
+BSON_DEPRECATED_FOR (bson_copy_to_excluding_noinit)
 BSON_EXPORT (void)
-bson_copy_to_excluding (const bson_t *src, bson_t *dst, const char *first_exclude, ...) BSON_GNUC_NULL_TERMINATED
-   BSON_GNUC_DEPRECATED_FOR (bson_copy_to_excluding_noinit);
+   bson_copy_to_excluding (const bson_t *src, bson_t *dst, const char *first_exclude, ...) BSON_GNUC_NULL_TERMINATED;
 
 /**
  * bson_copy_to_excluding_noinit:
@@ -531,8 +531,8 @@ bson_as_canonical_extended_json (const bson_t *bson, size_t *length);
  *
  * Returns: A newly allocated string that should be freed with bson_free().
  */
-BSON_EXPORT (char *)
-bson_as_json (const bson_t *bson, size_t *length) BSON_GNUC_DEPRECATED_FOR (bson_as_legacy_extended_json);
+BSON_DEPRECATED_FOR (bson_as_legacy_extended_json)
+BSON_EXPORT (char *) bson_as_json (const bson_t *bson, size_t *length);
 
 // `bson_as_legacy_extended_json` is a non-deprecated form of `bson_as_json`.
 BSON_EXPORT (char *)
@@ -562,8 +562,8 @@ bson_as_relaxed_extended_json (const bson_t *bson, size_t *length);
 
 
 /* like bson_as_json() but for outermost arrays. */
-BSON_EXPORT (char *)
-bson_array_as_json (const bson_t *bson, size_t *length) BSON_GNUC_DEPRECATED_FOR (bson_array_as_legacy_extended_json);
+BSON_DEPRECATED_FOR (bson_array_as_legacy_extended_json)
+BSON_EXPORT (char *) bson_array_as_json (const bson_t *bson, size_t *length);
 
 // `bson_array_as_legacy_extended_json` is a non-deprecated form of `bson_array_as_json`.
 BSON_EXPORT (char *)

src/libmongoc/doc/mongoc_read_prefs_get_hedge.rst

@@ -3,6 +3,11 @@
 mongoc_read_prefs_get_hedge()
 =============================
 
+.. deprecated:: MongoDB Server 8.0
+
+  Hedged reads are deprecated in MongoDB version 8.0 and will be removed in
+  a future release.
+
 Synopsis
 --------
 

src/libmongoc/doc/mongoc_read_prefs_set_hedge.rst

@@ -3,6 +3,11 @@
 mongoc_read_prefs_set_hedge()
 =============================
 
+.. deprecated:: MongoDB Server 8.0
+
+  Hedged reads are deprecated in MongoDB version 8.0 and will be removed in
+  a future release.
+
 Synopsis
 --------
 

src/libmongoc/doc/mongoc_read_prefs_t.rst

@@ -70,9 +70,19 @@ Max Staleness is also supported by sharded clusters of replica sets if all serve
 Hedged Reads
 ------------
 
-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.
+.. deprecated:: MongoDB Server 8.0
 
-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.
+  Hedged reads are deprecated in MongoDB version 8.0 and will be removed in
+  a future release.
+
+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.
+
+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.
 
 .. code-block:: none