CXX-3082 Add comprehensive examples (mongocxx) (#1216)

* Add missing docs for mongocxx::v_noabi::uri::k_default_uri
* Avoid CDRIVER-5732
* Add support for forking API examples
* Add support for running components with an instance object
* Add support for running components against a live server
* Add diagnostics for a component thread terminated via uncaught exception
* Add db locker to avoid read-write conflicts across examples
* Add helper to set majority read/write concern for collections
* Add EXAMPLES_COMPONENT_NAME_STR
* Add mongocxx instance examples
* Add mongocxx logger examples
* Add mongocxx URI examples
* Add mongocxx client examples
* Add mongocxx database examples
* Add mongocxx collection examples
* Add mongocxx operation exception examples

Author: eramongodb

.evergreen/test.sh

@@ -297,6 +297,9 @@ else
   # API version to example clients, so examples will fail when requireApiVersion
   # is true.
   if [[ -z "${MONGODB_API_VERSION:-}" ]]; then
+    # Avoid `[__NSCFConstantString initialize] may have been in progress in another thread when fork() was called.` errors on MacOS.
+    export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
+
     echo "Running examples..."
     if ! "${cmake_binary:?}" --build . --target run-examples --parallel 1 >|output.txt 2>&1; then
       # Only emit output on failure.

docs/api/mongocxx/examples/clients.md

@@ -0,0 +1,83 @@
+# Create a Client
+
+## Single
+
+### Basic Usage
+
+@snippet api/mongocxx/examples/clients/create/single/basic.cpp Example
+
+### With a Custom URI
+
+@snippet api/mongocxx/examples/clients/create/single/with_uri.cpp Example
+
+### With Client Options
+
+#### Stable API Options
+
+@snippet api/mongocxx/examples/clients/create/single/options/stable_api.cpp Example
+
+#### TLS Options
+
+@snippet api/mongocxx/examples/clients/create/single/options/tls.cpp Example
+
+#### Automatic Encryption Options
+
+@snippet api/mongocxx/examples/clients/create/single/options/auto_encryption.cpp Example
+
+#### APM Options
+
+@snippet api/mongocxx/examples/clients/create/single/options/apm.cpp Example
+
+## Pool
+
+### Basic Usage
+
+@snippet api/mongocxx/examples/clients/create/pool/basic.cpp Example
+
+### With Client Options
+
+@snippet api/mongocxx/examples/clients/create/pool/options.cpp Example
+
+### Try Acquire
+
+@snippet api/mongocxx/examples/clients/create/pool/try_acquire.cpp Example
+
+# Use a Client
+
+## List Databases
+
+@snippet api/mongocxx/examples/clients/use/list_databases.cpp Example
+
+## List Databases With Options
+
+@snippet api/mongocxx/examples/clients/use/list_databases_with_options.cpp Example
+
+## List Database Names
+
+@snippet api/mongocxx/examples/clients/use/list_database_names.cpp Example
+
+## List Database Names With Options
+
+@snippet api/mongocxx/examples/clients/use/list_database_names_with_options.cpp Example
+
+# Error Handling
+
+## Invalid Client
+
+@snippet api/mongocxx/examples/clients/errors/invalid_client.cpp Example
+
+## Wait Queue Timeout
+
+@snippet api/mongocxx/examples/clients/errors/wait_queue_timeout.cpp Example
+
+## Invalid Stable API Options
+
+@snippet api/mongocxx/examples/clients/errors/stable_api.cpp Example
+
+## TLS Not Enabled
+
+@snippet api/mongocxx/examples/clients/errors/tls.cpp Example
+
+## Invalid Auto Encryption Options
+
+@snippet api/mongocxx/examples/clients/errors/auto_encryption.cpp Example

docs/api/mongocxx/examples/collections.md

@@ -0,0 +1,113 @@
+# Obtain a Collection
+
+@snippet examples/api/mongocxx/examples/collections/obtain.cpp Example
+
+# Collection Operations
+
+## Drop a Collection
+
+@snippet examples/api/mongocxx/examples/collections/drop.cpp Example
+
+## Rename a Collection
+
+@snippet examples/api/mongocxx/examples/collections/rename.cpp Example
+
+## Set a Read Concern
+
+@snippet examples/api/mongocxx/examples/collections/rc.cpp Example
+
+## Set a Write Concern
+
+@snippet examples/api/mongocxx/examples/collections/wc.cpp Example
+
+## Set a Read Preference
+
+@snippet examples/api/mongocxx/examples/collections/rp.cpp Example
+
+# Index Operations
+
+## List Indexes
+
+@snippet examples/api/mongocxx/examples/collections/list_indexes.cpp Example
+
+## Create an Index
+
+@snippet examples/api/mongocxx/examples/collections/create_index.cpp Example
+
+## Create an Index With Options
+
+@snippet examples/api/mongocxx/examples/collections/create_index_with_options.cpp Example
+
+# Document Operations
+
+## Query the Number of Documents
+
+@snippet examples/api/mongocxx/examples/collections/count.cpp Example
+
+## Estimate the Number of Documents
+
+@snippet examples/api/mongocxx/examples/collections/estimate_count.cpp Example
+
+## Find a Document
+
+@snippet examples/api/mongocxx/examples/collections/find_one.cpp Example
+
+## Find Multiple Documents
+
+@snippet examples/api/mongocxx/examples/collections/find.cpp Example
+
+## Delete a Document
+
+@snippet examples/api/mongocxx/examples/collections/delete_one.cpp Example
+
+## Delete Many Documents
+
+@snippet examples/api/mongocxx/examples/collections/delete_many.cpp Example
+
+## Insert a Document
+
+@snippet examples/api/mongocxx/examples/collections/insert_one.cpp Example
+
+## Insert Many Documents
+
+@snippet examples/api/mongocxx/examples/collections/insert_many.cpp Example
+
+## Replace a Document
+
+@snippet examples/api/mongocxx/examples/collections/replace_one.cpp Example
+
+## Update a Document
+
+@snippet examples/api/mongocxx/examples/collections/update_one.cpp Example
+
+## Update Multiple Documents
+
+@snippet examples/api/mongocxx/examples/collections/update_many.cpp Example
+
+## Find and Delete a Document
+
+@snippet examples/api/mongocxx/examples/collections/find_one_and_delete.cpp Example
+
+## Find and Replace a Document
+
+@snippet examples/api/mongocxx/examples/collections/find_one_and_replace.cpp Example
+
+## Find and Update a Document
+
+@snippet examples/api/mongocxx/examples/collections/find_one_and_update.cpp Example
+
+## Find Distinct Values
+
+@snippet examples/api/mongocxx/examples/collections/distinct.cpp Example
+
+## Execute a Single Bulk Write Operation
+
+@snippet examples/api/mongocxx/examples/collections/write.cpp Example
+
+## Execute Multiple Bulk Write Operations
+
+@snippet examples/api/mongocxx/examples/collections/bulk_write.cpp Example
+
+## Execute an Aggregation Operation
+
+@snippet examples/api/mongocxx/examples/collections/aggregate.cpp Example

docs/api/mongocxx/examples/databases.md

@@ -0,0 +1,43 @@
+# Obtain a Database
+
+@snippet examples/api/mongocxx/examples/databases/obtain.cpp Example
+
+# Database Operations
+
+## Drop a Database
+
+@snippet examples/api/mongocxx/examples/databases/drop.cpp Example
+
+## Run a Command
+
+@snippet examples/api/mongocxx/examples/databases/run_command.cpp Example
+
+## Set a Read Concern
+
+@snippet examples/api/mongocxx/examples/databases/rc.cpp Example
+
+## Set a Write Concern
+
+@snippet examples/api/mongocxx/examples/databases/wc.cpp Example
+
+# Collection Operations
+
+## Create a Collection
+
+@snippet examples/api/mongocxx/examples/databases/create_collection.cpp Example
+
+## Create a Collection With Options
+
+@snippet examples/api/mongocxx/examples/databases/create_collection_with_options.cpp Example
+
+## Query a Collection Exists
+
+@snippet examples/api/mongocxx/examples/databases/has_collection.cpp Example
+
+## List Collections in the Database
+
+@snippet examples/api/mongocxx/examples/databases/list_collections.cpp Example
+
+## List Collection Names in the Database
+
+@snippet examples/api/mongocxx/examples/databases/list_collection_names.cpp Example

docs/api/mongocxx/examples/instance.md

@@ -0,0 +1,21 @@
+# Initialize the C++ Driver
+
+## Basic Usage
+
+@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
+
+@snippet api/mongocxx/examples/instance/recreation.cpp Example
+
+## Destroyed Instance
+
+@snippet api/mongocxx/examples/instance/destroyed.cpp Example

docs/api/mongocxx/examples/logger.md

@@ -0,0 +1,7 @@
+# Basic Usage
+
+@snippet api/mongocxx/examples/logger/basic_usage.cpp Example
+
+# Convert a Log Level to a String
+
+@snippet api/mongocxx/examples/logger/to_string.cpp Example

docs/api/mongocxx/examples/operation_exceptions.md

@@ -0,0 +1,11 @@
+# As a Regular Exception
+
+@warning The @ref mongocxx::server_error_category error category is overloaded ([CXX-834](https://jira.mongodb.org/browse/CXX-834)). The error code value may belong to the server, libmongoc, or libmongocrypt depending on the context. Use error code values with caution.
+
+@snippet examples/api/mongocxx/examples/operation_exceptions/regular.cpp Example
+
+# As an Operation Exception
+
+@note Using @ref mongocxx::exception for error handling is recommended for forward compatibility. ([CXX-2377](https://jira.mongodb.org/browse/CXX-2377))
+
+@snippet examples/api/mongocxx/examples/operation_exceptions/operation.cpp Example

docs/api/mongocxx/examples/uri.md

@@ -0,0 +1,33 @@
+# Create a URI
+
+## Basic Usage
+
+@snippet api/mongocxx/examples/uri/basic_usage.cpp Example
+
+## Default Value
+
+@snippet api/mongocxx/examples/uri/default_value.cpp Example
+
+# Query a URI
+
+## User Credentials
+
+@snippet api/mongocxx/examples/uri/userpass.cpp Example
+
+## List of Hosts
+
+@snippet api/mongocxx/examples/uri/hosts.cpp Example
+
+## Optional Options
+
+@snippet api/mongocxx/examples/uri/optional.cpp Example
+
+## All URI Options
+
+@snippet api/mongocxx/examples/uri/all_options.cpp Example
+
+# Error Handling
+
+## Invalid URI
+
+@snippet api/mongocxx/examples/uri/invalid.cpp Example

examples/api/bsoncxx/examples/bson_errors/big_string.hh

@@ -26,7 +26,8 @@ namespace examples {
 // Used to trigger builder append failure.
 struct big_string {
     // BSON_SIZE_MAX == 0x7FFFFFFF
-    std::size_t length{static_cast<std::size_t>(std::numeric_limits<std::int32_t>::max())};
+    // Leave some room for CDRIVER-5732.
+    std::size_t length{static_cast<std::size_t>(std::numeric_limits<std::int32_t>::max() - 32u)};
 
     // Allocate an UNINITIALIZED blob of data that will not be accessed due to length checks.
     // Leaving memory unitialized (rather than zero-init) should hopefully avoid slow and expensive

examples/api/concern.cpp

@@ -0,0 +1,46 @@
+// 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.
+
+#include <mongocxx/collection.hpp>
+#include <mongocxx/database.hpp>
+#include <mongocxx/read_concern.hpp>
+#include <mongocxx/write_concern.hpp>
+
+#include <examples/api/concern.hh>
+
+// Preferred default for most operations.
+mongocxx::collection set_rw_concern_majority(mongocxx::collection coll) {
+    coll.read_concern(rc_majority());
+    coll.write_concern(wc_majority());
+    return coll;
+}
+
+// Preferred default for most operations.
+mongocxx::database set_rw_concern_majority(mongocxx::database db) {
+    db.read_concern(rc_majority());
+    db.write_concern(wc_majority());
+    return db;
+}
+
+mongocxx::read_concern rc_majority() {
+    mongocxx::read_concern rc;
+    rc.acknowledge_level(mongocxx::read_concern::level::k_majority);
+    return rc;
+}
+
+mongocxx::write_concern wc_majority() {
+    mongocxx::write_concern wc;
+    wc.acknowledge_level(mongocxx::write_concern::level::k_majority);
+    return wc;
+}