Apply __cdecl to all exported functions (CXX-3092, CXX-3093) (#1202)

* Restrict macro guard tests to public headers

* Redefine export header macros in terms of ABI visibility

* Address -Wreserved-macro-identifier warnings in macro guard tests

* Disable -Wunused-macros warning for macro guard tests

* CXX-3093 Replace BSONCXX_API -> BSONCXX_ABI_EXPORT_CDECL

* CXX-3093 Replace MONGOCXX_API -> MONGOCXX_ABI_EXPORT_CDECL

* Address -Wweak-vtables warnings for exception classes

* Add __cdecl to main() in examples

* Include __cdecl in specialization of mongocxx::test_util::mock

* Include __cdecl in std::function<T> for exported symbols

* CDRIVER-5789 Workaround missing __cdecl in mongoc_log_func_t

* CXX-3093 Add changelog entry for ABI symbol removal

* CXX-3092 Enable /Gv when building test suite with MSVC

* doxygen: set ALWAYS_DETAILED_SEC = YES

* doxygen: set STRICT_PROTO_MATCHING = YES

* Disable C4251 and C4275 warnings for exception classes

* Scope "Downloading" messages to avoid misleading repeated output

* Also update debian_package_build.sh with examples include directory

* Remove private and generated config headers from macro guard tests

* Add coding guidelines section for virtual functions

* Add missing __cdecl in value::deleter_type declarations

* Remove stray use of MONGOCXX_CALL

Author: eramongodb

.evergreen/build_snapshot_rpm.sh

@@ -124,10 +124,10 @@ sudo mock -r ${config} --use-bootstrap-image --isolation=simple --copyin "${mock
 
 sudo mock -r ${config} --use-bootstrap-image --isolation=simple --cwd "/tmp/${build_dir}" --chroot -- /bin/sh -c "(
   rpm -Uvh ../mock-result/*.rpm &&
-  /usr/bin/g++ -I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -o runcommand_examples examples/mongocxx/mongodb.com/runcommand_examples.cpp -lmongocxx -lbsoncxx &&
-  /usr/bin/g++ -I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -o aggregation_examples examples/mongocxx/mongodb.com/aggregation_examples.cpp -lmongocxx -lbsoncxx &&
-  /usr/bin/g++ -I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -o index_examples examples/mongocxx/mongodb.com/index_examples.cpp -lmongocxx -lbsoncxx &&
-  /usr/bin/g++ -I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -o documentation_examples examples/mongocxx/mongodb.com/documentation_examples.cpp -lmongocxx -lbsoncxx
+  /usr/bin/g++ -I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -I. -o runcommand_examples examples/mongocxx/mongodb.com/runcommand_examples.cpp -lmongocxx -lbsoncxx &&
+  /usr/bin/g++ -I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -I. -o aggregation_examples examples/mongocxx/mongodb.com/aggregation_examples.cpp -lmongocxx -lbsoncxx &&
+  /usr/bin/g++ -I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -I. -o index_examples examples/mongocxx/mongodb.com/index_examples.cpp -lmongocxx -lbsoncxx &&
+  /usr/bin/g++ -I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -I. -o documentation_examples examples/mongocxx/mongodb.com/documentation_examples.cpp -lmongocxx -lbsoncxx
   )"
 
 if [ ! -e "${mock_root}/tmp/${build_dir}/runcommand_examples" ]; then

.evergreen/debian_package_build.sh

@@ -77,14 +77,13 @@ sudo DEB_BUILD_PROFILES="${DEB_BUILD_PROFILES}" chroot ./unstable-chroot /bin/ba
   LANG=C /bin/bash -x ./debian/build_snapshot.sh && \
   debc ../*.changes && \
   dpkg -i ../*.deb && \
-  /usr/bin/g++ ${MNMLSTC_INCLUDE:-}-I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -o runcommand_examples examples/mongocxx/mongodb.com/runcommand_examples.cpp -lmongocxx -lbsoncxx && \
-  /usr/bin/g++ ${MNMLSTC_INCLUDE:-}-I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -o aggregation_examples examples/mongocxx/mongodb.com/aggregation_examples.cpp -lmongocxx -lbsoncxx && \
-  /usr/bin/g++ ${MNMLSTC_INCLUDE:-}-I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -o index_examples examples/mongocxx/mongodb.com/index_examples.cpp -lmongocxx -lbsoncxx && \
-  /usr/bin/g++ ${MNMLSTC_INCLUDE:-}-I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -o documentation_examples examples/mongocxx/mongodb.com/documentation_examples.cpp -lmongocxx -lbsoncxx )"
+  /usr/bin/g++ ${MNMLSTC_INCLUDE:-}-I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -I. -o runcommand_examples examples/mongocxx/mongodb.com/runcommand_examples.cpp -lmongocxx -lbsoncxx && \
+  /usr/bin/g++ ${MNMLSTC_INCLUDE:-}-I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -I. -o aggregation_examples examples/mongocxx/mongodb.com/aggregation_examples.cpp -lmongocxx -lbsoncxx && \
+  /usr/bin/g++ ${MNMLSTC_INCLUDE:-}-I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -I. -o index_examples examples/mongocxx/mongodb.com/index_examples.cpp -lmongocxx -lbsoncxx && \
+  /usr/bin/g++ ${MNMLSTC_INCLUDE:-}-I/usr/include/bsoncxx/v_noabi -I/usr/include/mongocxx/v_noabi -I. -o documentation_examples examples/mongocxx/mongodb.com/documentation_examples.cpp -lmongocxx -lbsoncxx )"
 
 [ -e ./unstable-chroot/tmp/mongo-cxx-driver/runcommand_examples ] || (echo "Example 'runcommand_examples' was not built!" ; exit 1)
 [ -e ./unstable-chroot/tmp/mongo-cxx-driver/aggregation_examples ] || (echo "Example 'aggregation_examples' was not built!" ; exit 1)
 [ -e ./unstable-chroot/tmp/mongo-cxx-driver/index_examples ] || (echo "Example 'index_examples' was not built!" ; exit 1)
 [ -e ./unstable-chroot/tmp/mongo-cxx-driver/documentation_examples ] || (echo "Example 'documentation_examples' was not built!" ; exit 1)
 (cd ./unstable-chroot/tmp/ ; tar zcvf ../../deb.tar.gz *.dsc *.orig.tar.gz *.debian.tar.xz *.build *.deb)
-

CHANGELOG.md

@@ -22,6 +22,18 @@ Changes prior to 3.9.0 are documented as [release notes on GitHub](https://githu
 - A future minor release plans to raise the minimum supported MongoDB Server version from 3.6 to 4.0. This is in
 accordance with [MongoDB Software Lifecycle Schedules](https://www.mongodb.com/legal/support-policy/lifecycles).
 
+### Removed
+
+- Export of private member functions in bsoncxx:
+  - `bsoncxx::v_noabi::types::bson_value::value::value(const uint8_t*, uint32_t, uint32_t, uint32_t)`
+  - `bsoncxx::v_noabi::types::bson_value::view::_init(void*)`
+  - `bsoncxx::v_noabi::types::bson_value::view::view(const uint8_t*, uint32_t, uint32_t, uint32_t)`
+  - `bsoncxx::v_noabi::types::bson_value::view::view(void*)`
+- Export of private member functions in mongocxx:
+  - `mongocxx::v_noabi::options::change_stream::as_bson()`
+  - `mongocxx::v_noabi::options::aggregate::append(bsoncxx::v_noabi::builder::basic::document&)`
+  - `mongocxx::v_noabi::options::index::storage_options()`
+
 ## 3.10.3 [Unreleased]
 
 <!-- Will contain entries for the next patch release -->

Doxyfile

@@ -153,7 +153,7 @@ ABBREVIATE_BRIEF       =
 # description.
 # The default value is: NO.
 
-ALWAYS_DETAILED_SEC    = NO
+ALWAYS_DETAILED_SEC    = YES
 
 # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
 # inherited members of a class in the documentation of that class as if those
@@ -726,7 +726,7 @@ SORT_BY_SCOPE_NAME     = YES
 # accept a match between prototype and implementation in such cases.
 # The default value is: NO.
 
-STRICT_PROTO_MATCHING  = NO
+STRICT_PROTO_MATCHING  = YES
 
 # The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo
 # list. This list is created by putting \todo commands in the documentation.
@@ -2417,15 +2417,9 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = BSONCXX_API= \
-                         BSONCXX_CALL= \
-                         BSONCXX_DEPRECATED \
-                         BSONCXX_INLINE=inline \
+PREDEFINED             = BSONCXX_ABI_EXPORT_CDECL(...)=__VA_ARGS__ \
                          BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR= \
-                         MONGOCXX_API= \
-                         MONGOCXX_CALL= \
-                         MONGOCXX_DEPRECATED= \
-                         MONGOCXX_INLINE=inline \
+                         MONGOCXX_ABI_EXPORT_CDECL(...)=__VA_ARGS__ \
                          MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
@@ -2435,7 +2429,26 @@ PREDEFINED             = BSONCXX_API= \
 # definition found in the source code.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_AS_DEFINED      =
+EXPAND_AS_DEFINED      = BSONCXX_ABI_CDECL \
+                         BSONCXX_ABI_EXPORT \
+                         BSONCXX_ABI_NO_EXPORT \
+                         BSONCXX_API \
+                         BSONCXX_CALL \
+                         BSONCXX_DEPRECATED \
+                         BSONCXX_DEPRECATED_EXPORT \
+                         BSONCXX_DEPRECATED_NO_EXPORT \
+                         BSONCXX_INLINE \
+                         BSONCXX_PRIVATE \
+                         MONGOCXX_ABI_CDECL \
+                         MONGOCXX_ABI_EXPORT \
+                         MONGOCXX_ABI_NO_EXPORT \
+                         MONGOCXX_API \
+                         MONGOCXX_CALL \
+                         MONGOCXX_DEPRECATED \
+                         MONGOCXX_DEPRECATED_EXPORT \
+                         MONGOCXX_DEPRECATED_NO_EXPORT \
+                         MONGOCXX_INLINE \
+                         MONGOCXX_PRIVATE
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
 # remove all references to function-like macros that are alone on a line, have

benchmark/microbench.cpp

@@ -26,6 +26,8 @@ bool finished_running(const std::chrono::duration<std::uint32_t, std::milli>& cu
     return (curr_time > maxtime || (curr_time > mintime && iter > max_iter));
 }
 
+microbench::~microbench() = default;
+
 void microbench::run() {
     setup();
 

benchmark/microbench.hpp

@@ -67,7 +67,12 @@ class microbench {
     microbench(std::string&& name, double task_size, std::set<benchmark_type> tags = {})
         : _score{task_size}, _tags{tags}, _name{std::move(name)} {}
 
-    virtual ~microbench() = default;
+    virtual ~microbench();
+
+    microbench(microbench&&) = default;
+    microbench& operator=(microbench&&) = default;
+    microbench(const microbench&) = default;
+    microbench& operator=(const microbench&) = default;
 
     void run();
 

cmake/FetchCatch2.cmake

@@ -30,6 +30,11 @@ function(fetch_catch2)
         string(REPLACE " -Werror" "" CMAKE_C_FLAGS "${CMAKE_C_FLAGS}")
         string(REPLACE " -Werror" "" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
 
+        # Ensure consistent default calling convention with test executables.
+        if(MSVC)
+            string(APPEND CMAKE_CXX_FLAGS " /Gv")
+        endif()
+
         FetchContent_MakeAvailable(EP_Catch2)
 
         # Avoid building unnecessary targets. Use FetchContent_Declare(EXCLUDE_FROM_ALL) in CMake 3.28 and newer.

cmake/MacroGuardTest.cmake

@@ -80,14 +80,19 @@ function(add_macro_guard_test)
         "static_assert(compare_equal(\"abc\", \"abc\"), \"compare_equal() sanity check failed\");\n"
         "static_assert(!compare_equal(\"abc\", \"def\"), \"compare_equal() sanity check failed\");\n"
         "\n"
-        "#define _TO_STR(x) #x\n"
-        "#define TO_STR(x) _TO_STR(x)\n"
+        "#define TO_STR_1(x) #x\n"
+        "#define TO_STR(x) TO_STR_1(x)\n"
         "\n"
     )
 
     add_library(test_${PARSED_PROJECT_NAME}_macro_guards STATIC EXCLUDE_FROM_ALL)
     target_link_libraries(test_${PARSED_PROJECT_NAME}_macro_guards PRIVATE ${PARSED_PROJECT_TEST_PROPERTIES_TARGET})
 
+    # Avoid noisy warnings.
+    target_compile_options(test_${PARSED_PROJECT_NAME}_macro_guards PRIVATE
+        $<$<CXX_COMPILER_ID:GNU,Clang>:-Wno-unused-macros>
+    )
+
     # Test each header individually.
     foreach(header ${GUARDED_HEADERS})
         set(MACRO_GUARD_TEST "${MACRO_GUARD_TEST_PRELUDE}")

etc/coding_guidelines.md

@@ -144,3 +144,9 @@ class foo {
 ## Relational Operators
 
 - Prefer to use free functions
+
+## Virtual Functions
+
+- Define at least one virtual function out-of-line in a source file as the "key function" for the polymorphic class to avoid weak vtables.
+  - Use the virtual destructor as the key function if no other appropriate virtual function exists.
+  - Ensure all copy and move special member functions are defaulted, deleted, or defined if the virtual destructor is defined out-of-line.

examples/CMakeLists.txt

@@ -66,13 +66,16 @@ function(add_examples_executable source)
     add_executable(${target_name} EXCLUDE_FROM_ALL ${source})
     target_link_libraries(${target_name} PRIVATE ${PARSED_LIBRARIES})
 
+    # Permit `#include <examples/macros.hh>`.
+    target_include_directories(${target_name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/..)
+
     # Keep executables in separate directories.
     set_target_properties(${target_name} PROPERTIES
         OUTPUT_NAME ${name}
         RUNTIME_OUTPUT_DIRECTORY ${subdir}
     )
 
-    # Deliberately use `__vectorcall` by default with MSVC to catch missing `__cdecl`.
+    # Use `__vectorcall` by default with MSVC to catch missing `__cdecl`.
     target_compile_options(${target_name} PRIVATE "$<$<CXX_COMPILER_ID:MSVC>:/Gv>")
 
     # Keep build and run targets completely separate.
@@ -123,6 +126,12 @@ file(GLOB_RECURSE mongocxx_examples_sources
     "mongocxx/*.cpp"
 )
 
+file(GLOB_RECURSE examples_headers
+    RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
+    CONFIGURE_DEPENDS
+    "*.hh"
+)
+
 foreach(source ${api_examples_sources})
     add_examples_executable(${source} LIBRARIES mongocxx_target)
 endforeach()
@@ -155,6 +164,7 @@ set_local_dist (examples_DIST_local
    ${api_examples_sources}
    ${bsoncxx_examples_sources}
    ${mongocxx_examples_sources}
+   ${examples_headers}
    README.md
    add_subdirectory/.gitignore
    add_subdirectory/CMakeLists.txt

examples/bsoncxx/builder_basic.cpp

@@ -19,9 +19,11 @@
 #include <bsoncxx/builder/basic/kvp.hpp>
 #include <bsoncxx/types.hpp>
 
+#include <examples/macros.hh>
+
 using namespace bsoncxx;
 
-int main() {
+int EXAMPLES_CDECL main() {
     // bsoncxx::builder::basic presents a BSON-construction interface familiar to users of the
     // server's
     // BSON library or the Java driver.

examples/bsoncxx/builder_core.cpp

@@ -15,9 +15,11 @@
 #include <bsoncxx/builder/core.hpp>
 #include <bsoncxx/types.hpp>
 
+#include <examples/macros.hh>
+
 using namespace bsoncxx;
 
-int main() {
+int EXAMPLES_CDECL main() {
     // bsoncxx::builder::core is a low-level primitive that can be useful for building other
     // BSON abstractions. Most users should just use builder::stream or builder::basic.
 

examples/bsoncxx/builder_list.cpp

@@ -18,9 +18,11 @@
 #include <bsoncxx/types.hpp>
 #include <bsoncxx/types/bson_value/value.hpp>
 
+#include <examples/macros.hh>
+
 using namespace bsoncxx;
 
-int main() {
+int EXAMPLES_CDECL main() {
     using namespace bsoncxx::builder;
 
     //

examples/bsoncxx/builder_stream.cpp

@@ -17,9 +17,11 @@
 #include <bsoncxx/builder/stream/helpers.hpp>
 #include <bsoncxx/types.hpp>
 
+#include <examples/macros.hh>
+
 using namespace bsoncxx;
 
-int main() {
+int EXAMPLES_CDECL main() {
     using builder::stream::array;
     using builder::stream::document;
 

examples/bsoncxx/builder_stream_customization.cpp

@@ -19,6 +19,8 @@
 #include <bsoncxx/builder/stream/document.hpp>
 #include <bsoncxx/json.hpp>
 
+#include <examples/macros.hh>
+
 using namespace bsoncxx;
 
 // concatenates arbitrary ranges into an array context
@@ -68,7 +70,7 @@ range_kvp_appender<begin_t, end_t> make_range_kvp_appender(begin_t&& begin, end_
                                               std::forward<end_t>(end));
 }
 
-int main() {
+int EXAMPLES_CDECL main() {
     using builder::stream::array;
     using builder::stream::document;
     using builder::stream::finalize;

examples/bsoncxx/decimal128.cpp

@@ -20,9 +20,11 @@
 #include <bsoncxx/exception/exception.hpp>
 #include <bsoncxx/types.hpp>
 
+#include <examples/macros.hh>
+
 using namespace bsoncxx;
 
-int main() {
+int EXAMPLES_CDECL main() {
     // Convert a string to BSON Decimal128.
     decimal128 d128;
     try {

examples/bsoncxx/getting_values.cpp

@@ -21,9 +21,11 @@
 
 #include <bsoncxx/config/prelude.hpp>
 
+#include <examples/macros.hh>
+
 using namespace bsoncxx;
 
-int main() {
+int EXAMPLES_CDECL main() {
     using namespace builder::stream;
 
     builder::stream::document build_doc;

examples/bsoncxx/view_and_value.cpp

@@ -29,9 +29,11 @@
 #include <bsoncxx/types.hpp>
 #include <bsoncxx/types/bson_value/view.hpp>
 
+#include <examples/macros.hh>
+
 using namespace bsoncxx;
 
-int main() {
+int EXAMPLES_CDECL main() {
     // This example will cover the read-only BSON interface.
 
     // Lets first build up a non-trivial BSON document using the builder interface.

examples/macros.hh

@@ -0,0 +1,21 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#if defined(_MSC_VER)
+#define EXAMPLES_CDECL __cdecl
+#else
+#define EXAMPLES_CDECL
+#endif

examples/mongocxx/aggregate.cpp

@@ -22,10 +22,12 @@
 #include <mongocxx/pipeline.hpp>
 #include <mongocxx/uri.hpp>
 
+#include <examples/macros.hh>
+
 using bsoncxx::builder::basic::kvp;
 using bsoncxx::builder::basic::make_document;
 
-int main() {
+int EXAMPLES_CDECL main() {
     // The mongocxx::instance constructor and destructor initialize and shut down the driver,
     // respectively. Therefore, a mongocxx::instance must be created before using the driver and
     // must remain alive for as long as the driver is in use.

examples/mongocxx/automatic_client_side_field_level_encryption.cpp

@@ -32,6 +32,8 @@
 #include <mongocxx/options/data_key.hpp>
 #include <mongocxx/options/encrypt.hpp>
 
+#include <examples/macros.hh>
+
 using bsoncxx::builder::basic::kvp;
 using bsoncxx::builder::basic::make_document;
 
@@ -97,7 +99,7 @@ bsoncxx::document::value doc_from_file(std::string path) {
 
 }  // namespace
 
-int main() {
+int EXAMPLES_CDECL main() {
     instance inst{};
 
     // This must be the same master key that was used to create

examples/mongocxx/bulk_write.cpp

@@ -22,10 +22,12 @@
 #include <mongocxx/instance.hpp>
 #include <mongocxx/uri.hpp>
 
+#include <examples/macros.hh>
+
 using bsoncxx::builder::basic::kvp;
 using bsoncxx::builder::basic::make_document;
 
-int main() {
+int EXAMPLES_CDECL main() {
     // The mongocxx::instance constructor and destructor initialize and shut down the driver,
     // respectively. Therefore, a mongocxx::instance must be created before using the driver and
     // must remain alive for as long as the driver is in use.