MongoDB C++ Driver
mongocxx-3.10.2
|
Class representing a preference for how the driver routes read operations to members of a replica set or to a sharded cluster. More...
#include <read_preference.hpp>
Classes | |
struct | deprecated_tag |
Public Types | |
enum class | read_mode : std::uint8_t { k_primary , k_primary_preferred , k_secondary , k_secondary_preferred , k_nearest } |
Determines which members in a replica set are acceptable to read from. More... | |
Public Member Functions | |
read_preference () | |
Constructs a new read_preference with read_mode set to k_primary. | |
read_preference (read_mode mode) | |
Constructs a new read_preference. More... | |
read_preference (read_mode mode, bsoncxx::v_noabi::document::view_or_value tags) | |
Constructs a new read_preference with tags. More... | |
read_preference (const read_preference &) | |
Copy constructs a read_preference. | |
read_preference & | operator= (const read_preference &) |
Copy assigns a read_preference. | |
read_preference (read_preference &&) noexcept | |
Move constructs a read_preference. | |
read_preference & | operator= (read_preference &&) noexcept |
Move assigns a read_preference. | |
~read_preference () | |
Destroys a read_preference. | |
read_preference & | mode (read_mode mode) |
Sets a new mode for this read_preference. More... | |
read_mode | mode () const |
Returns the current read_mode for this read_preference. More... | |
read_preference & | tags (bsoncxx::v_noabi::document::view_or_value tag_set_list) |
Sets or updates the tag set list for this read_preference. More... | |
read_preference & | tags (bsoncxx::v_noabi::array::view_or_value tag_set_list) |
Sets or updates the tag set list for this read_preference. More... | |
stdx::optional< bsoncxx::v_noabi::document::view > | tags () const |
Sets or updates the tag set list for this read_preference. More... | |
read_preference & | max_staleness (std::chrono::seconds max_staleness) |
Sets the max staleness setting for this read_preference. More... | |
stdx::optional< std::chrono::seconds > | max_staleness () const |
Returns the current max staleness setting for this read_preference. More... | |
read_preference & | hedge (bsoncxx::v_noabi::document::view_or_value hedge) |
Sets the hedge document to be used for the read preference. More... | |
const stdx::optional< bsoncxx::v_noabi::document::view > | hedge () const |
Gets the current hedge document to be used for the read preference. More... | |
Friends | |
bool | operator== (const read_preference &, const read_preference &) |
Compares two read_preference objects for (in)-equality. | |
bool | operator!= (const read_preference &, const read_preference &) |
Compares two read_preference objects for (in)-equality. | |
Class representing a preference for how the driver routes read operations to members of a replica set or to a sharded cluster.
By default read operations are directed to the primary member in a replica set. Reading from the primary guarantees that read operations reflect the latest version of a document. However, by distributing some or all reads to secondary members of the replica set, you can improve read throughput or reduce latency for an application that does not require fully up-to-date data.
Read preference can be broadly specified by setting a mode. It is also possible to set tags in the read preference for more granular control, and to target specific members of a replica set via attributes other than their current state as a primary or secondary node. Furthermore, it is also possible to set a staleness threshold, such that the read is limited to targeting secondaries whose staleness is less than or equal to the given threshold.
Read preferences are ignored for direct connections to a single mongod instance. However, in order to perform read operations on a direct connection to a secondary member of a replica set, you must set a read preference that allows reading from secondaries.
|
strong |
Determines which members in a replica set are acceptable to read from.
mongocxx::v_noabi::read_preference::read_preference | ( | read_mode | mode | ) |
Constructs a new read_preference.
mode | Specifies the read_mode. |
mongocxx::v_noabi::read_preference::read_preference | ( | read_mode | mode, |
bsoncxx::v_noabi::document::view_or_value | tags | ||
) |
Constructs a new read_preference with tags.
mode | A read_preference read_mode. |
tags | A document representing tags to use for the read_preference. |
const stdx::optional<bsoncxx::v_noabi::document::view> mongocxx::v_noabi::read_preference::hedge | ( | ) | const |
Gets the current hedge document to be used for the read preference.
read_preference& mongocxx::v_noabi::read_preference::hedge | ( | bsoncxx::v_noabi::document::view_or_value | hedge | ) |
Sets the hedge document to be used for the read preference.
Sharded clusters running MongoDB 4.4 or later can dispatch read operations in parallel, returning the result from the fastest host and cancelling the unfinished operations.
This may be an empty document or a document of the form { enabled: <boolean> }.
Hedged reads are automatically enabled in MongoDB 4.4+ when using a nearest
read preference. To explicitly enable or disable hedging, the hedge
document must be passed. An empty document uses server defaults to control hedging, but the enabled
key may be set to true
or false
to explicitly enable or disable hedged reads.
hedge | The hedge document to set. For example, the document { enabled: true }. |
stdx::optional<std::chrono::seconds> mongocxx::v_noabi::read_preference::max_staleness | ( | ) | const |
Returns the current max staleness setting for this read_preference.
read_preference& mongocxx::v_noabi::read_preference::max_staleness | ( | std::chrono::seconds | max_staleness | ) |
Sets the max staleness setting for this read_preference.
Secondary servers with an estimated lag greater than this value will be excluded from selection under modes that allow secondaries.
Max staleness must be at least 90 seconds, and also at least the sum (in seconds) of the client's heartbeatFrequencyMS and the server's idle write period, which is 10 seconds. For general use, 90 seconds is the effective minimum. If less, an exception will be thrown when an operation is attempted.
Max staleness may only be used with MongoDB version 3.4 or later. If used with an earlier version, an exception will be thrown when an operation is attempted.
max_staleness | The new max staleness setting. It must be positive. |
mongocxx::v_noabi::logic_error | if the argument is invalid. |
read_mode mongocxx::v_noabi::read_preference::mode | ( | ) | const |
Returns the current read_mode for this read_preference.
read_preference& mongocxx::v_noabi::read_preference::mode | ( | read_mode | mode | ) |
Sets a new mode for this read_preference.
mode | The new read preference mode. |
stdx::optional<bsoncxx::v_noabi::document::view> mongocxx::v_noabi::read_preference::tags | ( | ) | const |
Sets or updates the tag set list for this read_preference.
read_preference& mongocxx::v_noabi::read_preference::tags | ( | bsoncxx::v_noabi::array::view_or_value | tag_set_list | ) |
Sets or updates the tag set list for this read_preference.
tag_set_list | Array of tag sets. |
read_preference& mongocxx::v_noabi::read_preference::tags | ( | bsoncxx::v_noabi::document::view_or_value | tag_set_list | ) |
Sets or updates the tag set list for this read_preference.
tag_set_list | Document representing the tag set list. |