Skip to content

v1::read_preference (CXX-3237, CXX-3238) #1505

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 17, 2025
Merged

v1::read_preference (CXX-3237, CXX-3238) #1505

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6f5956c
v1::read_preference (CXX-3237, CXX-3238)
eramongodb Nov 14, 2025
ab3ba77
Add important admonition to 4.2.0 release regarding v_noabi symbol re…
eramongodb Nov 17, 2025
dab1332
Drive-by fix documentation comment
eramongodb Nov 17, 2025
260ca14
Fix documentation for enum field setter
eramongodb Nov 17, 2025
d406149
Include tip to recompile against new mongocxx shared library
eramongodb Nov 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ Changes prior to 3.9.0 are documented as [release notes on GitHub](https://githu

## 4.2.0 [Unreleased]

> [!IMPORTANT]
> This release removes and changes the exports of many unstable ABI symbols.
> Recompilation is required to link against the mongocxx shared library for this release.

### Added

* To support incremental migration, the following entities are defined as equivalent to their renamed counterparts.
Expand Down
6 changes: 5 additions & 1 deletion src/mongocxx/include/mongocxx/v1/read_preference.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,6 @@ class read_preference {
/// - @ref read_mode::k_secondary
/// - @ref read_mode::k_secondary_preferred
/// - @ref read_mode::k_nearest
/// Any unsupported value is interpreted as @ref read_mode::k_primary.
///
/// @see
/// - [Read Preference Use Cases](https://www.mongodb.com/docs/manual/core/read-preference-use-cases/)
Expand Down Expand Up @@ -200,6 +199,11 @@ class read_preference {
}
/// @}
///

class internal;

private:
/* explicit(false) */ read_preference(void* impl);
};

} // namespace v1
Expand Down
200 changes: 128 additions & 72 deletions src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_preference.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,25 +14,35 @@

#pragma once

#include <mongocxx/read_preference-fwd.hpp> // IWYU pragma: export

//

#include <bsoncxx/v1/detail/macros.hpp>

#include <mongocxx/v1/read_preference.hpp>

#include <chrono>
#include <cstdint>
#include <memory>
#include <memory> // IWYU pragma: keep: backward compatibility, to be removed.
#include <string> // IWYU pragma: keep: backward compatibility, to be removed.
#include <utility>

#include <mongocxx/client-fwd.hpp>
#include <mongocxx/collection-fwd.hpp>
#include <mongocxx/database-fwd.hpp>
#include <mongocxx/events/topology_description-fwd.hpp>
#include <mongocxx/options/transaction-fwd.hpp>
#include <mongocxx/read_preference-fwd.hpp> // IWYU pragma: export
#include <mongocxx/search_index_view-fwd.hpp>
#include <mongocxx/uri-fwd.hpp>
#include <mongocxx/client-fwd.hpp> // IWYU pragma: keep: backward compatibility, to be removed.
#include <mongocxx/collection-fwd.hpp> // IWYU pragma: keep: backward compatibility, to be removed.
#include <mongocxx/database-fwd.hpp> // IWYU pragma: keep: backward compatibility, to be removed.
#include <mongocxx/events/topology_description-fwd.hpp> // IWYU pragma: keep: backward compatibility, to be removed.
#include <mongocxx/options/transaction-fwd.hpp> // IWYU pragma: keep: backward compatibility, to be removed.
#include <mongocxx/search_index_view-fwd.hpp> // IWYU pragma: keep: backward compatibility, to be removed.
#include <mongocxx/uri-fwd.hpp> // IWYU pragma: keep: backward compatibility, to be removed.

#include <bsoncxx/array/view.hpp>
#include <bsoncxx/array/view_or_value.hpp>
#include <bsoncxx/document/view.hpp>
#include <bsoncxx/document/view_or_value.hpp>
#include <bsoncxx/stdx/optional.hpp>

#include <mongocxx/options/transaction.hpp>
#include <mongocxx/options/transaction.hpp> // IWYU pragma: keep: backward compatibility, to be removed.

#include <mongocxx/config/prelude.hpp>

Expand All @@ -47,6 +57,9 @@ namespace v_noabi {
/// - [Read Preference (MongoDB Manual)](https://www.mongodb.com/docs/manual/core/read-preference/)
///
class read_preference {
private:
v1::read_preference _rp;

public:
///
/// Determines which members in a replica set are acceptable to read from.
Expand Down Expand Up @@ -90,7 +103,31 @@ class read_preference {
///
/// Constructs a new read_preference with read_mode set to k_primary.
///
MONGOCXX_ABI_EXPORT_CDECL() read_preference();
read_preference() = default;

///
/// Construct with the @ref mongocxx::v1 equivalent.
///
/* explicit(false) */ read_preference(v1::read_preference rp) : _rp{std::move(rp)} {}

///
/// Convert to the @ref mongocxx::v1 equivalent.
///
/// @par Postconditions:
/// - `other` is in an assign-or-destroy-only state.
///
/// @warning Invalidates all associated iterators and views.
///
explicit operator v1::read_preference() && {
return std::move(_rp);
}

///
/// Convert to the @ref mongocxx::v1 equivalent.
///
explicit operator v1::read_preference() const& {
return _rp;
}

// @cond DOXYGEN_DISABLE
struct deprecated_tag {};
Expand All @@ -104,10 +141,12 @@ class read_preference {
///
/// @deprecated Use @ref mode instead.
///
MONGOCXX_DEPRECATED MONGOCXX_ABI_EXPORT_CDECL() read_preference(read_mode mode);
Copy link
Collaborator

@kevinAlbs kevinAlbs Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I expect inlining the previously ABI exported methods is an ABI breaking change to the (unstable) v_noabi. I think that is OK. Consider noting ABI removals in the changelog (if not already planned) as done with previous ABI removal notes.

A generic note may be appropriate:

v_noabi ABI exports have been made inline. Consumers must recompile`

I expect many v_noabi classes will be re-implemented in terms of v1. And this may just be a useful heads up that a recompile is needed.

Copy link
Contributor Author

@eramongodb eramongodb Nov 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather than enumerating all of the individual exported symbols removed in the 4.2.0 release, added an "Important" admonition at the top of the 4.2.0 release section indicating to users that recompilation is required to link against the new library release. Users should be recompiling against every release given the lack of a stable ABI guarantee, but nevertheless, this release deserves a reminder.

MONGOCXX_DEPRECATED read_preference(read_mode mode) : read_preference{mode, deprecated_tag{}} {}

// @cond DOXYGEN_DISABLE
MONGOCXX_ABI_EXPORT_CDECL() read_preference(read_mode mode, deprecated_tag);
read_preference(read_mode mode, deprecated_tag) {
this->mode(mode);
}
// @endcond

///
Expand All @@ -123,40 +162,15 @@ class read_preference {
///
/// @deprecated Use @ref tags instead.
///
MONGOCXX_DEPRECATED MONGOCXX_ABI_EXPORT_CDECL() read_preference(
read_mode mode,
bsoncxx::v_noabi::document::view_or_value tags);
MONGOCXX_DEPRECATED read_preference(read_mode mode, bsoncxx::v_noabi::document::view_or_value tags)
: read_preference{mode, tags, deprecated_tag{}} {}

// @cond DOXYGEN_DISABLE
MONGOCXX_ABI_EXPORT_CDECL()
read_preference(read_mode mode, bsoncxx::v_noabi::document::view_or_value tags, deprecated_tag);
read_preference(read_mode mode, bsoncxx::v_noabi::document::view_or_value tags, deprecated_tag) {
this->mode(mode).tags(tags.view());
}
// @endcond

///
/// Copy constructs a read_preference.
///
MONGOCXX_ABI_EXPORT_CDECL() read_preference(read_preference const&);

///
/// Copy assigns a read_preference.
///
MONGOCXX_ABI_EXPORT_CDECL(read_preference&) operator=(read_preference const&);

///
/// Move constructs a read_preference.
///
MONGOCXX_ABI_EXPORT_CDECL() read_preference(read_preference&&) noexcept;

///
/// Move assigns a read_preference.
///
MONGOCXX_ABI_EXPORT_CDECL(read_preference&) operator=(read_preference&&) noexcept;

///
/// Destroys a read_preference.
///
MONGOCXX_ABI_EXPORT_CDECL() ~read_preference();

///
/// Sets a new mode for this read_preference.
///
Expand All @@ -167,14 +181,19 @@ class read_preference {
/// A reference to the object on which this member function is being called. This facilitates
/// method chaining.
///
MONGOCXX_ABI_EXPORT_CDECL(read_preference&) mode(read_mode mode);
read_preference& mode(read_mode mode) {
_rp.mode(static_cast<v1::read_preference::read_mode>(mode));
return *this;
}

///
/// Returns the current read_mode for this read_preference.
///
/// @return The current read_mode.
///
MONGOCXX_ABI_EXPORT_CDECL(read_mode) mode() const;
read_mode mode() const {
return static_cast<read_mode>(_rp.mode());
}

///
/// Sets or updates the tag set list for this read_preference.
Expand All @@ -189,8 +208,10 @@ class read_preference {
/// A reference to the object on which this member function is being called. This facilitates
/// method chaining.
///
MONGOCXX_ABI_EXPORT_CDECL(read_preference&)
tags(bsoncxx::v_noabi::document::view_or_value tag_set_list);
read_preference& tags(bsoncxx::v_noabi::document::view_or_value tag_set_list) {
_rp.tags(bsoncxx::v_noabi::to_v1(tag_set_list.view()));
return *this;
}

///
/// Sets or updates the tag set list for this read_preference.
Expand All @@ -205,19 +226,30 @@ class read_preference {
/// A reference to the object on which this member function is being called. This facilitates
/// method chaining.
///
MONGOCXX_ABI_EXPORT_CDECL(read_preference&)
tags(bsoncxx::v_noabi::array::view_or_value tag_set_list);
read_preference& tags(bsoncxx::v_noabi::array::view_or_value tag_set_list) {
_rp.tags(bsoncxx::v_noabi::to_v1(tag_set_list.view()));
return *this;
}

///
/// Sets or updates the tag set list for this read_preference.
/// Returns the current tag set list for this read_preference.
///
/// @return The optionally set current tag set list.
///
/// @see
/// - https://www.mongodb.com/docs/manual/core/read-preference-tags/
///
MONGOCXX_ABI_EXPORT_CDECL(bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view>)
tags() const;
bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> tags() const {
bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> ret;

auto const v = _rp.tags();

if (!v.empty()) {
ret.emplace(v);
}

return ret;
}

///
/// Sets the max staleness setting for this read_preference. Secondary
Expand Down Expand Up @@ -256,8 +288,13 @@ class read_preference {
///
/// @return The optionally current max staleness setting.
///
MONGOCXX_ABI_EXPORT_CDECL(bsoncxx::v_noabi::stdx::optional<std::chrono::seconds>)
max_staleness() const;
bsoncxx::v_noabi::stdx::optional<std::chrono::seconds> max_staleness() const {
return _rp.max_staleness();
}

BSONCXX_PRIVATE_WARNINGS_PUSH();
BSONCXX_PRIVATE_WARNINGS_DISABLE(GNU("-Wdeprecated-declarations"));
BSONCXX_PRIVATE_WARNINGS_DISABLE(MSVC(4996));

///
/// Sets the hedge document to be used for the read preference. Sharded clusters running MongoDB
Expand All @@ -279,8 +316,10 @@ class read_preference {
/// @return A reference to the object on which this member function is being called. This
/// facilitates method chaining.
///
MONGOCXX_DEPRECATED MONGOCXX_ABI_EXPORT_CDECL(read_preference&) hedge(
bsoncxx::v_noabi::document::view_or_value hedge);
MONGOCXX_DEPRECATED read_preference& hedge(bsoncxx::v_noabi::document::view_or_value hedge) {
_rp.hedge(bsoncxx::v_noabi::to_v1(hedge.view()));
return *this;
}

///
/// Gets the current hedge document to be used for the read preference.
Expand All @@ -290,34 +329,48 @@ class read_preference {
/// @return A hedge document if one was set.
///
MONGOCXX_DEPRECATED MONGOCXX_ABI_EXPORT_CDECL(bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> const)
hedge() const;
hedge() const {
bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> ret;
if (auto const opt = _rp.hedge()) {
ret.emplace(*opt);
}
return ret;
}

BSONCXX_PRIVATE_WARNINGS_POP();

///
/// @relates mongocxx::v_noabi::read_preference
///
/// Compares two read_preference objects for (in)-equality.
///
/// @{
friend MONGOCXX_ABI_EXPORT_CDECL(bool) operator==(read_preference const&, read_preference const&);
friend MONGOCXX_ABI_EXPORT_CDECL(bool) operator!=(read_preference const&, read_preference const&);
friend bool operator==(read_preference const& lhs, read_preference const& rhs) {
return (lhs.mode() == rhs.mode()) && (lhs.tags() == rhs.tags()) && (lhs.max_staleness() == rhs.max_staleness());
}

friend bool operator!=(read_preference const& lhs, read_preference const& rhs) {
return !(lhs == rhs);
}
/// @}
///

private:
friend ::mongocxx::v_noabi::client;
friend ::mongocxx::v_noabi::collection;
friend ::mongocxx::v_noabi::database;
friend ::mongocxx::v_noabi::events::topology_description;
friend ::mongocxx::v_noabi::options::transaction;
friend ::mongocxx::v_noabi::search_index_view;
friend ::mongocxx::v_noabi::uri;

class impl;
class internal;
};

read_preference(std::unique_ptr<impl>&& implementation);
///
/// Convert to the @ref mongocxx::v_noabi equivalent of `v`.
///
inline v_noabi::read_preference from_v1(v1::read_preference v) {
return {std::move(v)};
}

std::unique_ptr<impl> _impl;
};
///
/// Convert to the @ref mongocxx::v1 equivalent of `v`.
///
inline v1::read_preference to_v1(v_noabi::read_preference v) {
return v1::read_preference{std::move(v)};
}

} // namespace v_noabi
} // namespace mongocxx
Expand All @@ -328,3 +381,6 @@ class read_preference {
/// @file
/// Provides @ref mongocxx::v_noabi::read_preference.
///
/// @par Includes
/// - @ref mongocxx/v1/read_preference.hpp
///
Loading