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 class	read_mode : std::uint8_t {   k_primary = 0x01 , k_primary_preferred = 0x05 , k_secondary = 0x02 , k_secondary_preferred = 0x06 ,   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.
	read_preference (read_mode mode, bsoncxx::document::view_or_value tags)
	Constructs a new read_preference with tags.
	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.
void	mode (read_mode mode)
	Sets a new mode for this read_preference.
read_mode	mode () const
	Returns the current read_mode for this read_preference.
void	tags (bsoncxx::document::view_or_value tags)
	Sets or updates the tags for this read_preference.
stdx::optional< bsoncxx::document::view >	tags () const
	Returns the current tags for this read_preference.

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

read_mode

enum class 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

read_preference() [1/2]

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

explicit

Constructs a new read_preference.

Parameters

mode	Optional parameter to specify the read_mode, defaults to k_primary.

read_preference() [2/2]

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

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

http://docs.mongodb.org/manual/core/read-preference/#tag-sets

Member Function Documentation

mode() [1/2]

read_mode mongocxx::read_preference::mode

(

)

const

Returns the current read_mode for this read_preference.

Returns

The current read_mode.

mode() [2/2]

void mongocxx::read_preference::mode

(

read_mode

mode

)

Sets a new mode for this read_preference.

Parameters

mode	The new read preference mode.

tags() [1/2]

stdx::optional< bsoncxx::document::view > mongocxx::read_preference::tags

(

)

const

Returns the current tags for this read_preference.

Returns

The optionally set current tags.

tags() [2/2]

void mongocxx::read_preference::tags

(

bsoncxx::document::view_or_value

tags

)

Sets or updates the tags for this read_preference.

Parameters

tags	Document representing the tags.

---

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

• src/mongocxx/read_preference.hpp