CXX-3232 add bsoncxx v1 declarations #1412

eramongodb · 2025-05-28T21:06:32Z

Resolves CXX-3232. Followup to #1318, #1401, and #1402.

This is 2 out of an estimated 7 major PRs which in total are expected to resolve CXX-2745.

Top-Level Dependencies (CXX-3239)
bsoncxx v1 Interfaces (CXX-3232) (<-- you are here)
bsoncxx v1 Implementations (CXX-3233)
bsoncxx v_noabi Refactor (CXX-3234)
mongocxx v1 Interfaces (CXX-3236)
mongocxx v1 Implementations (CXX-3237)
mongocxx v_noabi Refactor (CXX-3238)

This PR introduces the very first set of v1 ABI exported symbols. 🎉

... only because MSVC complains otherwise. The rest will come as planned in CXX-3233 (impls).

Due to the volume of changes relative to the equivalent v_noabi interfaces, the bulk of relative changelog (v_noabi -> v1) and rationale for design decisions are documented inline as GitHub comments (coincidentally, exactly 100 comments in total).

In summary, notable changes include:

General Notes
- Nearly all preconditions are now documented and well-defined to instead throw an exception or yield an "invalid" state.
- Narrowing casts and discarded return values are now thoroughly accounted for as new error codes.
- All potentially-thrown exceptions are now documented and include the list of error codes which may be thrown.
v1::error
- All exceptions thrown by library components have a corresponding error code enumeration declared in v1::error with corresponding error category declared in v1::error::category.
- Error conditions source and type are provided as the primary user-facing error code query mechanism when component-specific error codes are not necessary.
v1::types::b_*
- All types are now consistently non-aggregate for list-initialization consistency.
- All "single underlying value" types now consistently support implicit conversion to said value.
- Multi-argument constructors are no longer explicit (always favored over value).
v1::types::view
- This type is now semitrivial (no user-provided non-default special member functions).
- Conversion to this type is now favored over conversion to value when applicable.
v1::types::value
- All (non-default) constructors are now explicit (b_* is always favored) so either b_* or view (cheap) is always preferred to value (expensive) when applicable.
- v1::types::id constructors are removed in favor of b_* and converting constructors.
- "Inline PIMPL" avoids redundant allocation while preserving encapsulation.
v1::element::view
- The "invalid" state is now clarified and thoroughly documented.
- "Inline PIMPL" leaves room for an alternative bool-based approach to "missing field" diagnostics (CXX-2120).
- Although not semitrivial, the class is still nothrow copyable.
- Equality comparison is defined as "same field in same BSON binary data". Relational comparison is also possible but deferred for now.
v1::document::view
- Now supports an "invalid" state without underlying BSON binary data.
v1::array::view
- Now (nearly) completely defined in terms of v1::document::view.
- API is extended for better parity with v1::document::view (CXX-2118).
v1::document::value
- Now default-constructible (CXX-939), equivalent to an "invalid" v1::document::view.
- deleter_type is now a std::function<T> instead of a function pointer.
- Customization points for to_bson and from_bson are now properly constrained.
v1::array::value
- Now (nearly) completely defined in terms of v1::document::value.
- API is extended for better parity with v1::document::value (CXX-2118).

eramongodb · 2025-05-28T21:12:20Z

.evergreen/scripts/abidiff-test.sh

+if (("$ret" & 0x03)); then # ABIDIFF_ERROR (1) | ABIDIFF_USAGE_ERROR (2)
+  echo "abidiff error" >&2
+  exit 1
+elif (("$ret" & 0x08)); then # ABIDIFF_ABI_INCOMPATIBLE_CHANGE (8).


Per abidiff docs:

The exit code of the abidiff command is either 0 if the ABI of the binaries being compared are equal, or non-zero if they differ or if the tool encountered an error. In the later case, the exit code is a 8-bits-wide bit field in which each bit has a specific meaning.

This PR introduces the first exported v1 ABI symbol: bsoncxx::v1::exception::~exception(). This new symbol triggered a non-zero exit code of ABIDIFF_ABI_CHANGE (4), which was incorrectly handled as incompatibility/failure. The script is updated to distinguish the individual error codes appropriately: we only care about incompatible changes. Compatible changes (such as this) will still be included in the resulting abidiff report.

eramongodb · 2025-05-28T21:14:40Z

src/bsoncxx/lib/bsoncxx/private/type_traits.hh

-                            std::is_trivially_copy_constructible<T>,
-                            std::is_trivially_copy_assignable<T>> {};
+struct is_semitrivial
+// https://gcc.gnu.org/onlinedocs/gcc-4.9.0/libstdc++/manual/manual/status.html


Unfortunately, GCC 4.X (used by RHEL 7) does not support the std::is_trivially_* type traits. Special-case this compiler version by simply assuming this property to be true (we have plenty of true coverage with other compilers and compiler versions on other platforms).

eramongodb · 2025-05-28T21:17:42Z

src/bsoncxx/lib/bsoncxx/v1/document/view.cpp

+static_assert(
+    is_nothrow_moveable<view::const_iterator>::value,
+    "bsoncxx::v1::document::view::const_iterator must be nothrow moveable");


Despite v1::document::view being semitrivial, its iterator is only nothrow moveable due to its internal v1::element::view data member.

eramongodb · 2025-05-28T21:17:51Z

src/bsoncxx/lib/bsoncxx/v1/array/view.cpp

+static_assert(
+    is_nothrow_moveable<view::const_iterator>::value,
+    "bsoncxx::v1::array::view::const_iterator must be nothrow moveable");


Despite v1::array::view being semitrivial, its iterator is only nothrow moveable due to its internal v1::element::view data member.

eramongodb · 2025-05-28T21:23:47Z

src/bsoncxx/lib/bsoncxx/v1/exception.cpp

+namespace bsoncxx {
+namespace v1 {
+
+exception::~exception() = default;


This is the key function for the bsoncxx::v1::exception class and the first v1 ABI symbol (along with the vtable) to be exported by the bsoncxx library. 🎉

Although this is meant a declarations-only PR, this definition is required to support successful builds with MSVC, as otherwise:

error LNK2019: unresolved external symbol "public: virtual __cdecl bsoncxx::v1::exception::~exception(void)" (??1exception@v1@bsoncxx@@UEAA@XZ) referenced in function "public: virtual void * __cdecl bsoncxx::v1::exception::`vector deleting destructor'(unsigned int)" (??_Eexception@v1@bsoncxx@@UEAAPEAXI@Z)

eramongodb · 2025-05-30T19:44:14Z

src/bsoncxx/include/bsoncxx/v1/document/value.hpp

+    deleter_type const& get_deleter() const {
+        return _data.get_deleter();
+    }


A non-const .get_deleter() is deliberately not provided to prevent "desync" of the deleter from the associated BSON binary data. Read-only access is nevertheless essential to support inspection of the type of underlying deleter, such as for v_noabi compatibility (e.g. "Is this deleter compatible with v_noabi::document::value::deleter_type?"). This will be explored in CXX-3234 (v_noabi refactor).

eramongodb · 2025-05-30T19:46:59Z

src/bsoncxx/include/bsoncxx/v1/document/value.hpp

+    ///
+    /// Implicitly convert to `this->view()`.
+    ///
+    /* explicit(false) */ operator v1::document::view() const {
+        return this->view();
+    }


Asymmetry: value -> view is implicit, but view -> value is explicit.

eramongodb · 2025-05-30T19:47:46Z

src/bsoncxx/include/bsoncxx/v1/types/value.hpp

+    ///
+    /// Implicitly convert to `this->view()`.
+    ///
+    /* explicit(false) */ operator v1::types::view() const {
+        return this->view();
+    }


Asymmetry: value -> view is implicit, but view -> value is explicit.

eramongodb · 2025-05-30T19:50:23Z

src/bsoncxx/include/bsoncxx/v1/document/value.hpp

+    ///
+    /// Return a view of the BSON binary data as a document.
+    ///
+    v1::document::view view() const {
+        return {_data.get(), _length};
+    }


All member functions below are defined in terms of v1::document::view, including error codes and Doxygen documentation.

Important
The new "invalid" state of a v1::document::view allows this conversion to be well-defined even when a value is default-initialized (_data.get() == nullptr).

eramongodb · 2025-05-30T19:51:09Z

src/bsoncxx/include/bsoncxx/v1/array/value.hpp

-class value {};
+class value {
+   private:
+    v1::document::value _value;


All behavior for this class is defined in terms of v1::document::value or v1::array::view, including error codes and Doxygen documentation.

eramongodb · 2025-06-02T14:42:12Z

src/bsoncxx/include/bsoncxx/v1/document/view.hpp

+/// @note This iterator almost satisfies Cpp17ForwardIterator, but `std::iterator_traits<T>::reference` is defined as
+/// `value_type`, similar to `std::vector<bool>::iterator` and `std::istreambuf_iterator<T>`. Therefore, this iterator
+/// only fully satisfies Cpp17InputIterator.


Update: renamed Legacy -> Cpp17 for consistency with standard spec for C++20 and newer (by P0896R4; cppreference still uses "Legacy", a leftover from when the C++20 spec was still being drafted) + restoring this comment due to the associated changes of the prior comment being lost by GitHub.

The v1 ABI interfaces address and clarify several issues with iterators that were identified during work on CXX-3082:

Missing const qualifiers on multiple member functions, e.g. auto const iter = doc.begin(); use(*iter); is ill-formed (?!).

iterator_category = std::forward_iterator_tag despite not actually satisfying the requirements of LegacyForwardIterator:

e.g. does not satisfy it: const_iterator -> *it -> T const&.

e.g. does not satisfy a == b -> std::addressof(*a) == std::addressof(*b).

Operations on an end iterator behavior, such as deference yielding an invalid element and increment yielding another end iterator, are ~~underdocumented~~ not documented at all.

v1::document::view::const_iterator (and v1::array::view::const_iterator) addresses all these issues by ensuring it properly satisfies and declares itself to be a LegacyInputIterator instead (even though it may provide some features of a LegacyForwardIterator).

kevinAlbs

The bsoncxx ABI v1 interfaces look well researched, and I really like the efforts towards better defining expected exceptions / minimizing preconditions.

kevinAlbs · 2025-06-06T14:25:53Z

src/bsoncxx/include/bsoncxx/v1/array/value.hpp

+    }
+
+    /// @copydoc v1::document::value::reset(v1::document::view const& v)
+    void reset(v1::array::view v) {


document::value::reset accepts a view const& but array::value::reset accepts a view. Consider making consistent.

Suggest using a non-reference view to avoid a "view to a view" type unless there is a benefit to accepting a view const&.

kevinAlbs · 2025-06-06T14:31:32Z

src/bsoncxx/include/bsoncxx/v1/array/value.hpp

+/// @par Includes
+/// - @ref bsoncxx/v1/array/view.hpp
+/// - @ref bsoncxx/v1/document/value.hpp
+/// - @ref bsoncxx/v1/element/view.hpp


Add include of element/view.hpp?

kevinAlbs · 2025-06-06T18:07:58Z

src/bsoncxx/include/bsoncxx/v1/array/view.hpp

+/// - @ref data() is not null, and
+/// - @ref size() is not less than `5` (the minimum size of a BSON document).
+///
+/// The BSON binary data being represented is only validated as minimally required to satisfy a requested operation.


Suggested change

/// The BSON binary data being represented is only validated as minimally required to satisfy a requested operation.

/// The BSON data being represented is only validated as minimally required to satisfy a requested operation.

Suggest removing "binary" to avoid mixing with the BSON binary type.

kevinAlbs · 2025-06-06T18:38:07Z

src/bsoncxx/include/bsoncxx/v1/array/view.hpp

+    ///
+    /// Return a const iterator to the element within the represented BSON array at index `i`.
+    ///
+    /// If this view is invalid, returns an end iterator.


Suggest documenting expectation if i is not found.

Also suggest documenting this is not a constant time operation. That may help warn users wanting to iterate over indexes like:

for (uint32_t i = 0; i < num_entries; i++) { sum += arr.view()[i].get_int32(); // Scans BSON each time! }

kevinAlbs · 2025-06-06T18:42:42Z

src/bsoncxx/include/bsoncxx/v1/decimal128.hpp

+    ///
+    /// Zero-initialize the byte representation.
+    ///
+    /// @note The result is equivalent to `"0E-6176"`, not `"0"`.


I would rather avoid a subtle quiet behavior change between v_noabi and v1. LGTM as proposed.

kevinAlbs · 2025-06-13T19:25:41Z

src/bsoncxx/include/bsoncxx/v1/types/view.hpp

+    ///
+    /// Initialize with `code` and `scope`.
+    ///
+    b_codewscope(v1::stdx::string_view code, v1::document::view scope) : code{code}, scope{scope} {}


consider adding a code-only constructor

I support leaving as-is as a minor simplification since the code-with-scope BSON type is deprecated.

kevinAlbs · 2025-06-13T19:26:36Z

src/bsoncxx/include/bsoncxx/v1/types/view.hpp

+    ///
+    /// Initialize with `increment` and `timestamp`.
+    ///
+    b_timestamp(std::uint32_t increment, std::uint32_t timestamp) : increment{increment}, timestamp{timestamp} {}


consider adding a increment-only constructor

I support leaving it out (as proposed) unless there is a known need.

kevinAlbs · 2025-06-17T16:51:39Z

src/bsoncxx/include/bsoncxx/v1/document/view.hpp

+
+   public:
+    ///
+    /// Initialize as an empty view.


Confirming: is v1::document::view initialized to an empty document intended for consistency with v_noabi::document::view?

If there were no precedent, I might rather the initialize to an invalid, but I expect that is a quiet behavior change that might be missed when migrating. So I support this even if it means a slight asymmetry between default constructed v1::document::value (invalid) and default constructed v1::document::view (invalid).

kevinAlbs · 2025-06-17T17:28:44Z

src/bsoncxx/include/bsoncxx/v1/types/view.hpp

+    /// When the type of `lhs` and `rhs` compare equal but are not a supported value (not defined by @ref
+    /// BSONCXX_V1_TYPES_XMACRO), the result is always `true`.


Instead, all v1 interfaces ensure equality comparison has no preconditions and cannot fail.

Confirming: is avoiding an exception intended to avoid preconditions in general? Or is equality treated specially to avoid throwing?

kevinAlbs · 2025-06-17T19:20:21Z

src/bsoncxx/include/bsoncxx/v1/oid.hpp

+    ///
+    /// The number of bytes required to represent an ObjectID.
+    ///
+    static constexpr BSONCXX_ABI_EXPORT std::size_t k_oid_length = 12;


No strong opinion. I am OK with the proposed change (appears consistent with v_noabi), but would not object to switching to an enum constant to avoid adding to the ABI.

@vector-of-bool do you have an opinion?

eramongodb self-assigned this May 28, 2025

eramongodb force-pushed the cxx-abi-v1-decls branch 2 times, most recently from b52a537 to 07f460e Compare May 30, 2025 17:52

CXX-3232 add v1 interface declarations

98521ae

eramongodb force-pushed the cxx-abi-v1-decls branch from 07f460e to 98521ae Compare May 30, 2025 19:02

eramongodb commented May 30, 2025

View reviewed changes

eramongodb marked this pull request as ready for review May 30, 2025 20:31

eramongodb requested a review from a team as a code owner May 30, 2025 20:31

eramongodb requested review from rcsanchez97, kevinAlbs and vector-of-bool and removed request for rcsanchez97 May 30, 2025 20:32

eramongodb changed the title ~~CXX-3232 add v1 interface declarations~~ CXX-3232 add bsoncxx v1 declarations May 30, 2025

eramongodb added 2 commits June 2, 2025 09:36

Use copydoc for v1::array::view iterators

7451133

Rename Legacy -> Cpp17 for consistency with C++20 spec

a5b2cde

eramongodb commented Jun 2, 2025

View reviewed changes

Merge remote-tracking branch 'upstream/master' into cxx-abi-v1-decls

0720b5d

kevinAlbs reviewed Jun 17, 2025

View reviewed changes

	/// The BSON binary data being represented is only validated as minimally required to satisfy a requested operation.
	/// The BSON data being represented is only validated as minimally required to satisfy a requested operation.

		/// When the type of `lhs` and `rhs` compare equal but are not a supported value (not defined by @ref
		/// BSONCXX_V1_TYPES_XMACRO), the result is always `true`.

CXX-3232 add bsoncxx v1 declarations #1412

Are you sure you want to change the base?

CXX-3232 add bsoncxx v1 declarations #1412

Uh oh!

Conversation

eramongodb commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eramongodb May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eramongodb Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kevinAlbs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

eramongodb commented May 28, 2025 •

edited

Loading

eramongodb May 30, 2025 •

edited

Loading

eramongodb Jun 2, 2025 •

edited

Loading