Loading...
Searching...
No Matches
mongocxx::v_noabi::read_preference Class Reference

`#include <mongocxx/v_noabi/mongocxx/read_preference.hpp>`

## Description

Describes how MongoDB clients route read operations to the members of a replica set or sharded cluster.

See also
  - Read Preference (MongoDB Manual)

## Public Types

enum class | read_mode : std::uint8_t
| Determines which members in a replica set are acceptable to read from. More...

## Public Member Functions

| read_preference ()=default
| Constructs a new read_preference with read_mode set to k_primary.
| read_preference (read_mode mode)
| Constructs a new read_preference.
| read_preference (read_mode mode, bsoncxx::v_noabi::document::view_or_value tags)
| Constructs a new read_preference with tags.
| read_preference (v1::read_preference rp)
| Construct with the mongocxx::v1 equivalent.
bsoncxx::v_noabi::stdx::optional< bsoncxx::v_noabi::document::view > const | hedge () const
| Gets the current hedge document to be used for the read preference.
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.
bsoncxx::v_noabi::stdx::optional< std::chrono::seconds > | max_staleness () const
| Returns the current max staleness setting for this read_preference.
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.
read_mode | mode () const
| Returns the current read_mode for this read_preference.
read_preference & | mode (read_mode mode)
| Sets a new mode for this read_preference.
| operator v1::read_preference () &&
| Convert to the mongocxx::v1 equivalent.
| operator v1::read_preference () const &
| Convert to the mongocxx::v1 equivalent.
bsoncxx::v_noabi::stdx::optional< bsoncxx::v_noabi::document::view > | tags () const
| Returns the current tag set list for this read_preference.
read_preference & | tags (bsoncxx::v_noabi::array::view_or_value tag_set_list)
| Sets or updates the tag set list for this read_preference.
read_preference & | tags (bsoncxx::v_noabi::document::view_or_value tag_set_list)
| Sets or updates the tag set list for this read_preference.

## Related Symbols

(Note that these are not member symbols.)
bool | operator== (read_preference const &lhs, read_preference const &rhs)
| Compares two read_preference objects for (in)-equality.
bool | operator!= (read_preference const &lhs, read_preference const &rhs)
| Compares two read_preference objects for (in)-equality.

## Member Enumeration Documentation

## read_mode

enum class mongocxx::v_noabi::read_preference::read_mode : std::uint8_t

strong

Determines which members in a replica set are acceptable to read from.

Warning
  Read preference tags are not respected when the mode is set to primary.
  All read preference modes except primary may return stale data because secondaries replicate operations from the primary with some delay. Ensure that your application can tolerate stale data if you choose to use a non-primary mode.

See also
  - https://www.mongodb.com/docs/manual/core/read-preference/#read-preference-modes

Enumerator
k_primary | Only read from a primary node.
k_primary_preferred | Prefer to read from a primary node.
k_secondary | Only read from secondary nodes.
k_secondary_preferred | Prefer to read from secondary nodes.
k_nearest | Read from the node with the lowest latency irrespective of state.

## Constructor & Destructor Documentation

## read_preference() [1/4]

mongocxx::v_noabi::read_preference::read_preference | ( |  | ) |

default

Constructs a new read_preference with read_mode set to k_primary.

## read_preference() [2/4]

mongocxx::v_noabi::read_preference::read_preference | ( | v1::read_preference | rp | ) |

inline

Construct with the mongocxx::v1 equivalent.

## read_preference() [3/4]

mongocxx::v_noabi::read_preference::read_preference | ( | read_mode | mode | ) |

inline

Constructs a new read_preference.

Parameters

  mode | Specifies the read_mode.

Deprecated
  Use mode instead.

## read_preference() [4/4]

mongocxx::v_noabi::read_preference::read_preference | ( | read_mode | mode,
|  | bsoncxx::v_noabi::document::view_or_value | tags )

inline

Constructs a new read_preference with tags.

Parameters

  mode | A read_preference read_mode.
  tags | A document representing tags to use for the read_preference.

See also
  - https://www.mongodb.com/docs/manual/core/read-preference/#tag-sets

Deprecated
  Use tags instead.

## Member Function Documentation

## hedge() [1/2]

bsoncxx::v_noabi::stdx::optional< bsoncxx::v_noabi::document::view > const mongocxx::v_noabi::read_preference::hedge | ( |  | ) | const

inline

Gets the current hedge document to be used for the read preference.

Deprecated
  Hedged reads are deprecated in MongoDB Server version 8.0.

Returns
  A hedge document if one was set.

## hedge() [2/2]

read_preference & mongocxx::v_noabi::read_preference::hedge | ( | bsoncxx::v_noabi::document::view_or_value | hedge | ) |

inline

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.

Parameters

  hedge | The hedge document to set. For example, the document { enabled: true }.

Deprecated
  Hedged reads are deprecated in MongoDB Server version 8.0.

Returns
  A reference to the object on which this member function is being called. This facilitates method chaining.

## max_staleness() [1/2]

bsoncxx::v_noabi::stdx::optional< std::chrono::seconds > mongocxx::v_noabi::read_preference::max_staleness | ( |  | ) | const

inline

Returns the current max staleness setting for this read_preference.

Returns
  The optionally current max staleness setting.

## max_staleness() [2/2]

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.

Note
  The max-staleness feature is designed to prevent badly-lagging servers from being selected. The staleness estimate is imprecise and shouldn't be used to try to select "up-to-date" secondaries.

Parameters

  max_staleness | The new max staleness setting. It must be positive.

Returns
  A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

  mongocxx::v_noabi::logic_error | if the argument is invalid.

## mode() [1/2]

read_mode mongocxx::v_noabi::read_preference::mode | ( |  | ) | const

inline

Returns the current read_mode for this read_preference.

Returns
  The current read_mode.

## mode() [2/2]

read_preference & mongocxx::v_noabi::read_preference::mode | ( | read_mode | mode | ) |

inline

Sets a new mode for this read_preference.

Parameters

  mode | The new read preference mode.

Returns
  A reference to the object on which this member function is being called. This facilitates method chaining.

## operator v1::read_preference() [1/2]

mongocxx::v_noabi::read_preference::operator v1::read_preference | ( |  | ) | &&

inline explicit

Convert to the mongocxx::v1 equivalent.

Postconditions:
  - *this is in an assign-or-destroy-only state.

Warning
  Invalidates all associated views.

## operator v1::read_preference() [2/2]

mongocxx::v_noabi::read_preference::operator v1::read_preference | ( |  | ) | const &

inline explicit

Convert to the mongocxx::v1 equivalent.

## tags() [1/3]

bsoncxx::v_noabi::stdx::optional< bsoncxx::v_noabi::document::view > mongocxx::v_noabi::read_preference::tags | ( |  | ) | const

inline

Returns the current tag set list for this read_preference.

Returns
  The optionally set current tag set list.

See also
  - https://www.mongodb.com/docs/manual/core/read-preference-tags/

## tags() [2/3]

read_preference & mongocxx::v_noabi::read_preference::tags | ( | bsoncxx::v_noabi::array::view_or_value | tag_set_list | ) |

inline

Sets or updates the tag set list for this read_preference.

Parameters

  tag_set_list | Array of tag sets.

See also
  - https://www.mongodb.com/docs/manual/core/read-preference-tags/

Returns
  A reference to the object on which this member function is being called. This facilitates method chaining.

## tags() [3/3]

read_preference & mongocxx::v_noabi::read_preference::tags | ( | bsoncxx::v_noabi::document::view_or_value | tag_set_list | ) |

inline

Sets or updates the tag set list for this read_preference.

Parameters

  tag_set_list | Document representing the tag set list.

See also
  - https://www.mongodb.com/docs/manual/core/read-preference-tags/

Returns
  A reference to the object on which this member function is being called. This facilitates method chaining.

## Friends And Related Symbol Documentation

## operator!=

bool operator!= | ( | read_preference const & | lhs,
|  | read_preference const & | rhs )

friend

Compares two read_preference objects for (in)-equality.

## operator==

bool operator== | ( | read_preference const & | lhs,
|  | read_preference const & | rhs )

friend

Compares two read_preference objects for (in)-equality.

The documentation for this class was generated from the following file:

- mongocxx/v_noabi/mongocxx/read_preference.hpp