MongoDB C++ Driver  mongocxx-3.0.0
Public Types | Public Member Functions | List of all members
mongocxx::read_preference Class Reference

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>

Public Types

enum  read_mode : std::uint8_t {
  read_mode::k_primary = 0x01, read_mode::k_primary_preferred = 0x05, read_mode::k_secondary = 0x02, read_mode::k_secondary_preferred = 0x06,
  read_mode::k_nearest = 0x0A
}
 Determines which members in a replica set are acceptable to read from. More...
 

Public Member Functions

 read_preference (read_mode mode=read_mode::k_primary)
 Constructs a new read_preference. More...
 
 read_preference (read_mode mode, bsoncxx::document::view_or_value tags)
 Constructs a new read_preference with tags. More...
 
 read_preference (const read_preference &)
 Copy constructs a read_preference.
 
read_preferenceoperator= (const read_preference &)
 Copy assigns a read_preference.
 
 read_preference (read_preference &&) noexcept
 Move constructs a read_preference.
 
read_preferenceoperator= (read_preference &&) noexcept
 Move assigns a read_preference.
 
 ~read_preference ()
 Destroys a read_preference.
 
void 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...
 
void tags (bsoncxx::document::view_or_value tags)
 Sets or updates the tags for this read_preference. More...
 
stdx::optional< bsoncxx::document::viewtags () const
 Returns the current tags for this read_preference. More...
 

Detailed Description

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.

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.

See also
http://docs.mongodb.org/manual/core/read-preference/

Member Enumeration Documentation

enum mongocxx::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
http://docs.mongodb.org/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

mongocxx::read_preference::read_preference ( read_mode  mode = read_mode::k_primary)
explicit

Constructs a new read_preference.

Parameters
modeOptional parameter to specify the read_mode, defaults to k_primary.
mongocxx::read_preference::read_preference ( read_mode  mode,
bsoncxx::document::view_or_value  tags 
)

Constructs a new read_preference with tags.

Parameters
modeA read_preference read_mode.
tagsA document representing tags to use for the read_preference.
See also
http://docs.mongodb.org/manual/core/read-preference/#tag-sets

Member Function Documentation

void mongocxx::read_preference::mode ( read_mode  mode)

Sets a new mode for this read_preference.

Parameters
modeThe new read preference mode.
read_mode mongocxx::read_preference::mode ( ) const

Returns the current read_mode for this read_preference.

Returns
The current read_mode.
void mongocxx::read_preference::tags ( bsoncxx::document::view_or_value  tags)

Sets or updates the tags for this read_preference.

Parameters
tagsDocument representing the tags.
stdx::optional<bsoncxx::document::view> mongocxx::read_preference::tags ( ) const

Returns the current tags for this read_preference.

Returns
The optionally set current tags.

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