MongoDB C++ Driver  mongocxx-3.10.2
Public Member Functions | Static Public Member Functions | List of all members
mongocxx::v_noabi::instance Class Reference

Class representing an instance of the MongoDB driver. More...

#include <instance.hpp>

Public Member Functions

 instance ()
 Creates an instance of the driver.
 
 instance (std::unique_ptr< logger > logger)
 Creates an instance of the driver with a user provided log handler. More...
 
 instance (instance &&) noexcept
 Move constructs an instance of the driver.
 
instanceoperator= (instance &&) noexcept
 Move assigns an instance of the driver.
 
 ~instance ()
 Destroys an instance of the driver.
 

Static Public Member Functions

static instancecurrent ()
 Returns the current unique instance of the driver. More...
 

Detailed Description

Class representing an instance of the MongoDB driver.

The constructor and destructor initialize and shut down the driver, respectively. Therefore, an instance must be created before using the driver and must remain alive until all other mongocxx objects are destroyed. After the instance destructor runs, the driver may not be used.

Exactly one instance must be created in a given program. Not constructing an instance or constructing more than one instance in a program are errors, even if the multiple instances have non-overlapping lifetimes.

The following is a correct example of using an instance in a program, as the instance is kept alive for as long as the driver is in use:

#include <mongocxx/client.hpp>
#include <mongocxx/instance.hpp>
#include <mongocxx/uri.hpp>
int main() {
...
}
Class representing a client connection to MongoDB.
Definition: client.hpp:61
Class representing an instance of the MongoDB driver.
Definition: instance.hpp:80
Class representing a MongoDB connection string URI.
Definition: uri.hpp:47

An example of using instance incorrectly might look as follows:

#include <mongocxx/client.hpp>
#include <mongocxx/instance.hpp>
#include <mongocxx/uri.hpp>
client get_client() {
return client;
} // ERROR! The instance is no longer alive after this function returns.
int main() {
mongocxx::v_noabi::client conn = get_client();
...
}

For examples of more advanced usage of instance, see examples/mongocxx/instance_management.cpp.

Constructor & Destructor Documentation

◆ instance()

mongocxx::v_noabi::instance::instance ( std::unique_ptr< logger logger)

Creates an instance of the driver with a user provided log handler.

Parameters
loggerThe logger that the driver will direct log messages to.
Exceptions
mongocxx::v_noabi::logic_errorif an instance already exists.

Member Function Documentation

◆ current()

static instance& mongocxx::v_noabi::instance::current ( )
static

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.

The documentation for this class was generated from the following file: