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).

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CXX-3232 add bsoncxx v1 declarations #1412

CXX-3232 add bsoncxx v1 declarations #1412

Uh oh!

eramongodb commented May 28, 2025 •

edited

Loading

Uh oh!

eramongodb May 28, 2025

Uh oh!

eramongodb May 28, 2025

Uh oh!

eramongodb May 28, 2025

Uh oh!

eramongodb May 28, 2025

Uh oh!

eramongodb May 28, 2025

Uh oh!

eramongodb May 30, 2025

Uh oh!

eramongodb May 30, 2025

Uh oh!

eramongodb May 30, 2025

Uh oh!

eramongodb May 30, 2025

Uh oh!

eramongodb May 30, 2025 •

edited

Loading

Uh oh!

eramongodb Jun 2, 2025 •

edited

Loading

Uh oh!

Uh oh!

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!

Uh oh!

eramongodb commented May 28, 2025 •

edited

Loading

eramongodb May 30, 2025 •

edited

Loading

eramongodb Jun 2, 2025 •

edited

Loading