CXX-3324 remove all use of instance::current() (#1438)

* Document recommendations and workarounds for replacing current() in user code

Author: eramongodb

CHANGELOG.md

@@ -25,6 +25,26 @@ Changes prior to 3.9.0 are documented as [release notes on GitHub](https://githu
   - Apple Clang 13.1 with Xcode 13.4.1 (from Apple Clang 5.1 with Xcode 5.1).
   - MSVC 19.0.24210 with Visual Studio 2015 Update 3 (from MSVC 19.0.23506 with Visual Studio 2015 Update 1).
 
+### Deprecated
+
+- `mongocxx::v_noabi::instance::current()` is "for internal use only". The `instance` constructor(s) should be used instead.
+  - Creating the `instance` object in the scope of `main()`, or in an appropriate (non-global) scope such that its (non-static) lifetime is valid for the duration of all other mongocxx library operations, is recommended over the following workarounds.
+  - If there is only _one_ call to `current()` present within an application, it may be replaced with a static local variable:
+    ```cpp
+    // Before:
+    mongocxx::instance::current();
+
+    // After:
+    static mongocxx::instance instance; // Only ONE instance object!
+    ```
+  - If there are _multiple_ calls to `current()` present within an application, they may be replaced with a call to a user-defined function containing the static local variable:
+    ```cpp
+    mongocxx::instance& mongocxx_instance() {
+      static mongocxx::instance instance; // Only ONE instance object!
+      return instance;
+    }
+    ```
+
 ### Removed
 
 - Support for MongoDB Server 4.2.

docs/api/mongocxx/examples/instance.md

@@ -4,12 +4,6 @@
 
 @snippet api/mongocxx/examples/instance/basic_usage.cpp Example
 
-## With Static Lifetime
-
-@warning This pattern depends on an exit-time destructor with indeterminate order relative to other objects with static lifetime being destroyed.
-
-@snippet api/mongocxx/examples/instance/current.cpp Example
-
 # Errors
 
 ## Instance Recreation

examples/api/mongocxx/examples/instance/basic_usage.cpp

@@ -32,8 +32,6 @@ void example() {
         // Initialize the MongoDB C++ Driver by constructing the instance object.
         mongocxx::instance instance;
 
-        EXPECT(&mongocxx::instance::current() == &instance);
-
         // Use mongocxx library interfaces at this point.
         use(mongocxx::client{});
 

examples/api/mongocxx/examples/instance/current.cpp

@@ -37,11 +37,11 @@ void example() {
     }
 
     try {
-        auto& instance = mongocxx::instance::current(); // Throws.
+        mongocxx::instance instance; // Throws.
 
         EXPECT(false && "should not reach this point");
     } catch (mongocxx::exception const& ex) {
-        EXPECT(ex.code() == mongocxx::error_code::k_instance_destroyed);
+        EXPECT(ex.code() == mongocxx::error_code::k_cannot_recreate_instance);
     }
 }
 // [Example]

examples/api/mongocxx/examples/instance/destroyed.cpp

@@ -26,17 +26,13 @@ void example() {
     {
         mongocxx::instance instance;
 
-        EXPECT(&mongocxx::instance::current() == &instance);
-
         try {
             mongocxx::instance another_instance; // Throws.
 
             EXPECT(false && "should not reach this point");
         } catch (mongocxx::exception const& ex) {
             EXPECT(ex.code() == mongocxx::error_code::k_cannot_recreate_instance);
         }
-
-        EXPECT(&mongocxx::instance::current() == &instance);
     }
 }
 // [Example]

examples/api/mongocxx/examples/instance/recreation.cpp

@@ -111,19 +111,7 @@ class instance {
     instance& operator=(instance const&) = delete;
 
     ///
-    /// Returns the current unique instance of the driver. If an instance was explicitly created,
-    /// that will be returned. If no instance has yet been created, a default instance will be
-    /// constructed and returned. If a default instance is constructed, its destruction will be
-    /// sequenced according to the rules for the destruction of static local variables at program
-    /// exit (see http://en.cppreference.com/w/cpp/utility/program/exit).
-    ///
-    /// Note that, if you need to configure the instance in any way (e.g. with a logger), you cannot
-    /// use this method to cause the instance to be constructed. You must explicitly create an
-    /// properly configured instance object. You can, however, use this method to obtain that
-    /// configured instance object.
-    ///
-    /// @note This method is intended primarily for test authors, where managing the lifetime of the
-    /// instance w.r.t. the test framework can be problematic.
+    /// @warning For internal use only!
     ///
     static MONGOCXX_ABI_EXPORT_CDECL(instance&) current();
 

src/mongocxx/include/mongocxx/v_noabi/mongocxx/instance.hpp

@@ -137,8 +137,10 @@ add_executable(test_driver
 target_link_libraries(test_driver PRIVATE spec_test_common client_helpers)
 
 add_executable(test_logging v_noabi/logging.cpp)
+target_compile_definitions(test_logging PRIVATE MONGOCXX_TEST_DISABLE_MAIN_INSTANCE)
 
 add_executable(test_instance v_noabi/instance.cpp)
+target_compile_definitions(test_instance PRIVATE MONGOCXX_TEST_DISABLE_MAIN_INSTANCE)
 
 add_executable(test_crud_specs spec/crud.cpp)
 target_link_libraries(test_crud_specs PRIVATE spec_test_common client_helpers)

src/mongocxx/test/CMakeLists.txt

@@ -14,8 +14,14 @@
 
 #include <mongocxx/v1/config/export.hpp>
 
+#include <mongocxx/instance.hpp>
+
 #include <catch2/catch_session.hpp>
 
 int MONGOCXX_ABI_CDECL main(int argc, char* argv[]) {
+#if defined(MONGOCXX_TEST_DISABLE_MAIN_INSTANCE)
     return Catch::Session().run(argc, argv);
+#else
+    return ((void)mongocxx::instance(), Catch::Session().run(argc, argv));
+#endif
 }

src/mongocxx/test/catch.cpp

@@ -26,8 +26,6 @@ using namespace mongocxx;
 TEST_CASE(
     "creation of write_concern passes universal parameters to c-driver's methods",
     "[write_concern][base][c-driver]") {
-    instance::current();
-
     SECTION("when journal is requested, mongoc_write_concern_set_journal is called with true") {
         bool journal_called = false;
         bool journal_value = false;
@@ -60,8 +58,6 @@ TEST_CASE(
 }
 
 TEST_CASE("write_concern is called with w MAJORITY", "[write_concern][base][c-driver]") {
-    instance::current();
-
     bool w_called = false, wmajority_called = false, wtag_called = false;
     auto w_instance = libmongoc::write_concern_set_w.create_instance();
     auto wmajority_instance = libmongoc::write_concern_set_wmajority.create_instance();
@@ -88,8 +84,6 @@ TEST_CASE("write_concern is called with w MAJORITY", "[write_concern][base][c-dr
 }
 
 TEST_CASE("write_concern is called with a number of necessary confirmations", "[write_concern][base][c-driver]") {
-    instance::current();
-
     bool w_called = false, wmajority_called = false, wtag_called = false;
     int w_value = 0;
     int const expected_w = 5;
@@ -122,8 +116,6 @@ TEST_CASE("write_concern is called with a number of necessary confirmations", "[
 }
 
 TEST_CASE("write_concern is called with a tag", "[write_concern][base][c-driver]") {
-    instance::current();
-
     bool w_called = false, wmajority_called = false, wtag_called = false;
     std::string wtag_value;
     std::string const expected_wtag("MultiDataCenter");