# Poco::MongoDB

# class ReadPreference

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

Primary

Read from primary only

PrimaryPreferred

Read from primary, fallback to secondary

Secondary

Read from secondary only

SecondaryPreferred

Read from secondary, fallback to primary

Nearest

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,
Poco::Int64 heartbeatFrequencyUs = 10000000
) const;

Selects eligible servers from the topology based on this read preference. heartbeatFrequencyUs is the topology monitoring interval in microseconds, used in the maxStalenessSeconds calculation per the MongoDB Server Selection spec. See: https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.md Defaults to 10 seconds (10000000 us) per the MongoDB specification. 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