CXX-3320 migrate instance and logger to mongocxx::v1 (#1469)

Author: eramongodb

.evergreen/scripts/test.sh

@@ -289,8 +289,23 @@ else
     command -V valgrind
     valgrind --version
     run_test() {
+      valgrind_args=(
+        "--leak-check=full"
+        "--track-origins=yes"
+        "--num-callers=50"
+        "--error-exitcode=1"
+        "--error-limit=no"
+        "--read-var-info=yes"
+        "--suppressions=../etc/memcheck.suppressions"
+      )
+
+      # Avoid noisy diagnostics caused by deliberate subprocess termination.
+      if [[ "${1:?}" =~ test_instance ]]; then
+        valgrind_args+=("--trace-children=no")
+      fi
+
       echo "Running ${1:?}..."
-      valgrind --leak-check=full --track-origins=yes --num-callers=50 --error-exitcode=1 --error-limit=no --read-var-info=yes --suppressions=../etc/memcheck.suppressions "${1:?}" "${test_args[@]:?}" || return
+      valgrind "${1:?}" "${test_args[@]:?}" || return
       echo "Running ${1:?}... done."
     }
   fi
@@ -304,7 +319,6 @@ else
   run_test ./src/mongocxx/test/test_command_monitoring_specs
   run_test ./src/mongocxx/test/test_instance
   run_test ./src/mongocxx/test/test_transactions_specs
-  run_test ./src/mongocxx/test/test_logging
   run_test ./src/mongocxx/test/test_retryable_reads_specs
   run_test ./src/mongocxx/test/test_read_write_concern_specs
   run_test ./src/mongocxx/test/test_unified_format_specs

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

@@ -17,6 +17,7 @@
 //
 
 #include <string>
+#include <system_error>
 
 #include <bsoncxx/private/immortal.hh>
 #include <bsoncxx/private/type_traits.hh>

src/mongocxx/include/mongocxx/v1/exception.hpp

@@ -20,6 +20,13 @@
 
 #include <mongocxx/v1/detail/prelude.hpp>
 
+#include <bsoncxx/v1/detail/macros.hpp>
+
+#include <mongocxx/v1/config/export.hpp>
+
+#include <system_error>
+#include <type_traits>
+
 namespace mongocxx {
 namespace v1 {
 
@@ -28,14 +35,60 @@ namespace v1 {
 ///
 /// @attention This feature is experimental! It is not ready for use!
 ///
-enum class source_errc {};
+enum class source_errc {
+    zero,       ///< Zero.
+    mongocxx,   ///< From the mongocxx library.
+    mongoc,     ///< From the mongoc library.
+    mongocrypt, ///< From the mongocrypt library.
+    server,     ///< From the MongoDB server.
+};
+
+///
+/// The error category for @ref mongocxx::v1::source_errc.
+///
+/// @attention This feature is experimental! It is not ready for use!
+///
+MONGOCXX_ABI_EXPORT_CDECL(std::error_category const&) source_error_category();
+
+///
+/// Support implicit conversion to `std::error_condition`.
+///
+/// @attention This feature is experimental! It is not ready for use!
+///
+inline std::error_condition make_error_condition(source_errc code) {
+    return {static_cast<int>(code), v1::source_error_category()};
+}
 
 ///
 /// Enumeration identifying the type (cause) of a @ref mongocxx::v1 error.
 ///
 /// @attention This feature is experimental! It is not ready for use!
 ///
-enum class type_errc {};
+enum class type_errc {
+    zero,             ///< Zero.
+    invalid_argument, ///< An invalid argument passed to the throwing function.
+    runtime_error,    ///< An erroneous condition was detected at runtime.
+};
+
+///
+/// The error category for @ref mongocxx::v1::type_errc.
+///
+/// @attention This feature is experimental! It is not ready for use!
+///
+MONGOCXX_ABI_EXPORT_CDECL(std::error_category const&) type_error_category();
+
+///
+/// Support implicit conversion to `std::error_condition`.
+///
+/// @attention This feature is experimental! It is not ready for use!
+///
+inline std::error_condition make_error_condition(type_errc code) {
+    return {static_cast<int>(code), v1::type_error_category()};
+}
+
+BSONCXX_PRIVATE_WARNINGS_PUSH();
+BSONCXX_PRIVATE_WARNINGS_DISABLE(MSVC(4251));
+BSONCXX_PRIVATE_WARNINGS_DISABLE(MSVC(4275));
 
 ///
 /// Base class for all exceptions thrown by @ref mongocxx::v1.
@@ -45,11 +98,29 @@ enum class type_errc {};
 ///
 /// @attention This feature is experimental! It is not ready for use!
 ///
-class exception {};
+class exception : public std::system_error {
+   public:
+    ~exception() override;
+
+    exception(exception&&) noexcept = default;
+    exception& operator=(exception&&) noexcept = default;
+    exception(exception const&) = default;
+    exception& operator=(exception const&) = default;
+
+    using std::system_error::system_error;
+};
+
+BSONCXX_PRIVATE_WARNINGS_POP();
 
 } // namespace v1
 } // namespace mongocxx
 
+template <>
+struct std::is_error_condition_enum<mongocxx::v1::source_errc> : true_type {};
+
+template <>
+struct std::is_error_condition_enum<mongocxx::v1::type_errc> : true_type {};
+
 #include <mongocxx/v1/detail/postlude.hpp>
 
 ///

src/mongocxx/include/mongocxx/v1/instance.hpp

@@ -20,6 +20,14 @@
 
 #include <mongocxx/v1/detail/prelude.hpp>
 
+#include <mongocxx/v1/logger-fwd.hpp>
+
+#include <mongocxx/v1/config/export.hpp>
+
+#include <memory>
+#include <system_error>
+#include <type_traits>
+
 namespace mongocxx {
 namespace v1 {
 
@@ -50,15 +58,123 @@ namespace v1 {
 /// @par Special exemptions
 /// Only the following API are permitted to be used outside the lifetime of an instance object:
 /// - @ref mongocxx::v1::logger
+/// - @ref mongocxx::v1::default_logger
 ///
 /// @see
 /// - [Initialization and Cleanup (mongoc)](https://mongoc.org/libmongoc/current/init-cleanup.html)
 ///
-class instance {};
+class instance {
+   private:
+    class impl;
+    std::unique_ptr<impl> _impl;
+
+   public:
+    ///
+    /// Cleanup the mongocxx (and mongoc) library.
+    ///
+    /// Calls [`mongoc_cleanup()`](https://mongoc.org/libmongoc/current/mongoc_cleanup.html).
+    ///
+    MONGOCXX_ABI_EXPORT_CDECL() ~instance();
+
+    ///
+    /// This class is not moveable.
+    ///
+    instance(instance&&) = delete;
+
+    ///
+    /// This class is not moveable.
+    ///
+    instance& operator=(instance&&) = delete;
+
+    ///
+    /// This class is not copyable.
+    ///
+    instance(instance const&) = delete;
+
+    ///
+    /// This class is not copyable.
+    ///
+    instance& operator=(instance const&) = delete;
+
+    ///
+    /// Initialize the mongoc library with unstructured log messages disabled.
+    ///
+    /// Calls [`mongoc_init()`](https://mongoc.org/libmongoc/current/mongoc_init.html) after disabling unstructured
+    /// log messages by calling `mongoc_log_set_handler(nullptr, nullptr)`.
+    ///
+    /// @important To use mongoc's default log message handler, construct this object with
+    /// @ref instance(v1::default_logger tag) instead.
+    ///
+    /// @throws mongocxx::v1::exception with @ref mongocxx::v1::instance::errc::multiple_instances if an `instance`
+    /// object has already been created.
+    ///
+    /// @see
+    /// - [Custom Log Handlers (mongoc)](https://mongoc.org/libmongoc/current/unstructured_log.html#custom-log-handlers)
+    ///
+    MONGOCXX_ABI_EXPORT_CDECL() instance();
+
+    ///
+    /// Initialize the mongoc library with the custom unstructured log message handler.
+    ///
+    /// Calls [`mongoc_init`](https://mongoc.org/libmongoc/current/mongoc_init.html) after registering the custom
+    /// unstructured log handler by calling `mongoc_log_set_handler()`.
+    ///
+    /// @param handler Disable unstructured logging when null.
+    ///
+    /// @throws mongocxx::v1::exception with @ref mongocxx::v1::instance::errc::multiple_instances if an `instance`
+    /// object has already been created.
+    ///
+    /// @see
+    /// - [Custom Log Handlers (mongoc)](https://mongoc.org/libmongoc/current/unstructured_log.html#custom-log-handlers)
+    ///
+    explicit MONGOCXX_ABI_EXPORT_CDECL() instance(std::unique_ptr<v1::logger> handler);
+
+    ///
+    /// Initialize the mongoc library with its default unstructured log handler.
+    ///
+    /// Calls [`mongoc_init`](https://mongoc.org/libmongoc/current/mongoc_init.html) without registering any custom
+    /// unstructured log handler.
+    ///
+    /// @param tag Unused: only for overload resolution.
+    ///
+    /// @throws mongocxx::v1::exception with @ref mongocxx::v1::instance::errc::multiple_instances if an `instance`
+    /// object has already been created.
+    ///
+    explicit MONGOCXX_ABI_EXPORT_CDECL() instance(v1::default_logger tag);
+
+    ///
+    /// Errors codes which may be returned by @ref mongocxx::v1::instance.
+    ///
+    /// @attention This feature is experimental! It is not ready for use!
+    ///
+    enum class errc {
+        zero,               ///< Zero.
+        multiple_instances, ///< Cannot construct multiple instance objects in a given process.
+    };
+
+    ///
+    /// The error category for @ref mongocxx::v1::instance::errc.
+    ///
+    /// @attention This feature is experimental! It is not ready for use!
+    ///
+    static MONGOCXX_ABI_EXPORT_CDECL(std::error_category const&) error_category();
+
+    ///
+    /// Support implicit conversion to `std::error_code`.
+    ///
+    /// @attention This feature is experimental! It is not ready for use!
+    ///
+    friend std::error_code make_error_code(errc v) {
+        return {static_cast<int>(v), error_category()};
+    }
+};
 
 } // namespace v1
 } // namespace mongocxx
 
+template <>
+struct std::is_error_code_enum<mongocxx::v1::instance::errc> : true_type {};
+
 #include <mongocxx/v1/detail/postlude.hpp>
 
 ///

src/mongocxx/include/mongocxx/v1/logger-fwd.hpp

@@ -16,12 +16,17 @@
 
 #include <mongocxx/v1/detail/prelude.hpp>
 
+//
+
+#include <mongocxx/v1/config/export.hpp>
+
 namespace mongocxx {
 namespace v1 {
 
 enum class log_level;
 
-class logger;
+class MONGOCXX_ABI_EXPORT logger;
+
 class default_logger;
 
 } // namespace v1