Annotate and document "hedge" APIs as deprecated

Author: vector-of-bool

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
 

src/libmongoc/src/mongoc/mongoc-cmd.c

@@ -15,6 +15,7 @@
  */
 
 
+#include <mlib/config.h>
 #include <mongoc/mongoc-cmd-private.h>
 #include <mongoc/mongoc-read-prefs-private.h>
 #include <mongoc/mongoc-trace-private.h>
@@ -375,7 +376,10 @@ _mongoc_cmd_parts_assemble_mongos (mongoc_cmd_parts_t *parts, const mongoc_serve
       max_staleness_seconds = mongoc_read_prefs_get_max_staleness_seconds (parts->read_prefs);
 
       tags = mongoc_read_prefs_get_tags (parts->read_prefs);
+      mlib_diagnostic_push ();
+      mlib_disable_deprecation_warnings ();
       hedge = mongoc_read_prefs_get_hedge (parts->read_prefs);
+      mlib_diagnostic_pop ();
    }
 
    if (server_stream->must_use_primary) {

src/libmongoc/src/mongoc/mongoc-read-prefs.c

@@ -15,6 +15,7 @@
  */
 
 
+#include <mlib/config.h>
 #include <mongoc/mongoc-error-private.h>
 #include <mongoc/mongoc-read-prefs-private.h>
 #include <mongoc/mongoc-trace-private.h>
@@ -234,7 +235,10 @@ _apply_read_preferences_mongos (const mongoc_read_prefs_t *read_prefs,
       max_staleness_seconds = mongoc_read_prefs_get_max_staleness_seconds (read_prefs);
 
       tags = mongoc_read_prefs_get_tags (read_prefs);
+      mlib_diagnostic_push ();
+      mlib_disable_deprecation_warnings ();
       hedge = mongoc_read_prefs_get_hedge (read_prefs);
+      mlib_diagnostic_pop ();
    }
 
    /* Server Selection Spec says:
@@ -308,7 +312,11 @@ mongoc_read_prefs_append_contents_to_bson (const mongoc_read_prefs_t *read_prefs
    if (read_prefs) {
       // Other content is only available for non-NULL read_prefs
       int64_t max_staleness_seconds = mongoc_read_prefs_get_max_staleness_seconds (read_prefs);
+
+      mlib_diagnostic_push ();
+      mlib_disable_deprecation_warnings ();
       const bson_t *hedge = mongoc_read_prefs_get_hedge (read_prefs);
+      mlib_diagnostic_pop ();
       const bson_t *tags = mongoc_read_prefs_get_tags (read_prefs);
 
       if ((flags & MONGOC_READ_PREFS_CONTENT_FLAG_TAGS) && !bson_empty (tags) &&

src/libmongoc/src/mongoc/mongoc-read-prefs.h

@@ -49,28 +49,40 @@ typedef enum {
 
 MONGOC_EXPORT (mongoc_read_prefs_t *)
 mongoc_read_prefs_new (mongoc_read_mode_t read_mode) BSON_GNUC_WARN_UNUSED_RESULT;
+
 MONGOC_EXPORT (mongoc_read_prefs_t *)
 mongoc_read_prefs_copy (const mongoc_read_prefs_t *read_prefs) BSON_GNUC_WARN_UNUSED_RESULT;
+
 MONGOC_EXPORT (void)
 mongoc_read_prefs_destroy (mongoc_read_prefs_t *read_prefs);
+
 MONGOC_EXPORT (mongoc_read_mode_t)
 mongoc_read_prefs_get_mode (const mongoc_read_prefs_t *read_prefs);
+
 MONGOC_EXPORT (void)
 mongoc_read_prefs_set_mode (mongoc_read_prefs_t *read_prefs, mongoc_read_mode_t mode);
+
 MONGOC_EXPORT (const bson_t *)
 mongoc_read_prefs_get_tags (const mongoc_read_prefs_t *read_prefs);
+
 MONGOC_EXPORT (void)
 mongoc_read_prefs_set_tags (mongoc_read_prefs_t *read_prefs, const bson_t *tags);
+
 MONGOC_EXPORT (void)
 mongoc_read_prefs_add_tag (mongoc_read_prefs_t *read_prefs, const bson_t *tag);
+
 MONGOC_EXPORT (int64_t)
 mongoc_read_prefs_get_max_staleness_seconds (const mongoc_read_prefs_t *read_prefs);
+
 MONGOC_EXPORT (void)
 mongoc_read_prefs_set_max_staleness_seconds (mongoc_read_prefs_t *read_prefs, int64_t max_staleness_seconds);
-MONGOC_EXPORT (const bson_t *)
-mongoc_read_prefs_get_hedge (const mongoc_read_prefs_t *read_prefs);
-MONGOC_EXPORT (void)
-mongoc_read_prefs_set_hedge (mongoc_read_prefs_t *read_prefs, const bson_t *hedge);
+
+BSON_DEPRECATED ("Hedged reads are deprecated in MongoDB 8.0 and will be removed in a future release")
+MONGOC_EXPORT (const bson_t *) mongoc_read_prefs_get_hedge (const mongoc_read_prefs_t *read_prefs);
+
+BSON_DEPRECATED ("Hedged reads are deprecated in MongoDB 8.0 and will be removed in a future release")
+MONGOC_EXPORT (void) mongoc_read_prefs_set_hedge (mongoc_read_prefs_t *read_prefs, const bson_t *hedge);
+
 MONGOC_EXPORT (bool)
 mongoc_read_prefs_is_valid (const mongoc_read_prefs_t *read_prefs);