Library: MongoDB
Package: MongoDB
Header: Poco/MongoDB/ReadPreference.h
Description
Configures read preference mode and constraints for MongoDB operations.
Read preferences determine which replica set members receive read operations. The five read preference modes are:
- Primary: Read from the primary only (default, strongest consistency) - PrimaryPreferred: Read from primary, fallback to secondary - Secondary: Read from secondary only (distributes load) - SecondaryPreferred: Read from secondary, fallback to primary - Nearest: Read from any available member (primary or secondary)
Additional constraints: - Tag sets: Target specific replica set members by tags - Max staleness: Limit how stale secondary data can be
LIMITATIONS: The Nearest mode does NOT measure actual network round-trip time (RTT). It simply allows selection of any available member. True latency-based server selection is not implemented.
Examples:
ReadPreference primary(ReadPreference::Primary);
ReadPreference secondary(ReadPreference::Secondary);
ReadPreference nearest(ReadPreference::Nearest);
// With tag set (e.g., datacenter-aware routing)
Document tags;
tags.add("dc", "east");
tags.add("rack", "1");
ReadPreference geoPreference(ReadPreference::Nearest, tags);
THREAD SAFETY: This class is immutable after construction and therefore thread-safe.
Member Summary
Member Functions: maxStalenessSeconds, mode, nearest, operator =, primary, primaryPreferred, secondary, secondaryPreferred, selectServers, tags, toString
Enumerations
Mode
Read preference mode enumeration
Read from primary only
Read from primary, fallback to secondary
Read from secondary only
Read from secondary, fallback to primary
Read from any available member (no RTT measurement)
Constructors
ReadPreference
explicit ReadPreference(
Mode mode = Primary
);
Creates a ReadPreference with the specified mode.
ReadPreference
ReadPreference(
const ReadPreference & other
);
Copy constructor.
ReadPreference
ReadPreference(
ReadPreference && other
) noexcept;
Move constructor.
ReadPreference
ReadPreference(
Mode mode,
const Document & tags,
Poco::Int64 maxStalenessSeconds = NO_MAX_STALENESS
);
Creates a ReadPreference with mode, tag set, and optional max staleness. maxStalenessSeconds: maximum replication lag in seconds (-1 for no limit)
Destructor
~ReadPreference
~ReadPreference();
Destroys the ReadPreference.
Member Functions
maxStalenessSeconds 
[[nodiscard]]
Poco::Int64 maxStalenessSeconds() const;
Returns the max staleness in seconds, or NO_MAX_STALENESS if not set.
mode
[[nodiscard]]
Mode mode() const;
Returns the read preference mode.
nearest 
static ReadPreference nearest();
Factory method for Nearest read preference.
operator =
ReadPreference & operator = (
const ReadPreference & other
);
Assignment operator.
operator =
ReadPreference & operator = (
ReadPreference && other
) noexcept;
Move assignment operator.
primary
static ReadPreference primary();
Factory method for Primary read preference.
primaryPreferred
static ReadPreference primaryPreferred();
Factory method for PrimaryPreferred read preference.
secondary
static ReadPreference secondary();
Factory method for Secondary read preference.
secondaryPreferred
static ReadPreference secondaryPreferred();
Factory method for SecondaryPreferred read preference.
selectServers
[[nodiscard]]
std::vector < ServerDescription > selectServers(
const TopologyDescription & topology
) const;
Selects eligible servers from the topology based on this read preference. Returns a vector of eligible servers. If no servers match, returns an empty vector.
tags
[[nodiscard]]
const Document & tags() const;
Returns the tag set for server selection.
toString
[[nodiscard]]
std::string toString() const;
Returns a string representation of the read preference.
Variables
NO_MAX_STALENESS
static const Poco::Int64 NO_MAX_STALENESS = - 1;
Constant indicating no max staleness constraint