MongoDB C++ Driver  mongocxx-3.7.0
Public Types | Public Member Functions | List of all members
mongocxx::write_concern Class Reference

Class representing the server-side requirement for reporting the success of a write operation. More...

#include <write_concern.hpp>

Public Types

enum  level
 A class to represent the special case values for write_concern::nodes. More...
 

Public Member Functions

 write_concern ()
 Constructs a new write_concern.
 
 write_concern (const write_concern &)
 Copy constructs a write_concern.
 
write_concernoperator= (const write_concern &)
 Copy assigns a write_concern.
 
 write_concern (write_concern &&) noexcept
 Move constructs a write_concern.
 
write_concernoperator= (write_concern &&) noexcept
 Move assigns a write_concern.
 
 ~write_concern ()
 Destroys a write_concern.
 
void journal (bool journal)
 Sets the journal parameter for this write concern. More...
 
void nodes (std::int32_t confirm_from)
 Sets the number of nodes that are required to acknowledge the write before the operation is considered successful. More...
 
void acknowledge_level (level confirm_level)
 Sets the acknowledge level. More...
 
void majority (std::chrono::milliseconds timeout)
 Requires that a majority of the nodes in a replica set acknowledge a write operation before it is considered a success. More...
 
void tag (stdx::string_view tag)
 Sets the name representing the server-side getLastErrorMode entry containing the list of nodes that must acknowledge a write operation before it is considered a success. More...
 
void timeout (std::chrono::milliseconds timeout)
 Sets an upper bound on the time a write concern can take to be satisfied. More...
 
bool journal () const
 Gets the current status of the journal parameter. More...
 
stdx::optional< std::int32_t > nodes () const
 Gets the current number of nodes that this write_concern requires operations to reach. More...
 
level acknowledge_level () const
 Gets the current acknowledgment level. More...
 
stdx::optional< std::string > tag () const
 Gets the current getLastErrorMode that is required by this write_concern. More...
 
bool majority () const
 Gets whether the majority of nodes is currently required by this write_concern. More...
 
std::chrono::milliseconds timeout () const
 Gets the current timeout for this write_concern. More...
 
bool is_acknowledged () const
 Gets whether this write_concern requires an acknowledged write. More...
 
bsoncxx::document::value to_document () const
 Gets the document form of this write_concern. More...
 

Friends

bool operator== (const write_concern &, const write_concern &)
 Compares two write_concern objects for (in)-equality.
 
bool operator!= (const write_concern &, const write_concern &)
 Compares two write_concern objects for (in)-equality.
 

Detailed Description

Class representing the server-side requirement for reporting the success of a write operation.

The strength of the write concern setting determines the level of guarantees that you will receive from MongoDB regarding write durability.

Weaker requirements that provide fewer guarantees report on success quickly while stronger requirements that provide greater guarantees will take longer (or potentially forever, if the write_concern's requirements are not satisfied and no timeout is set).

MongoDB drivers allow for different levels of write concern to better address the specific needs of applications. Clients may adjust write concern to ensure that the most important operations persist successfully to an entire MongoDB deployment. However, for other less critical operations, clients can adjust the write concern to ensure better performance rather than persistence to the entire deployment.

See also
https://docs.mongodb.com/manual/core/write-concern/

Member Enumeration Documentation

◆ level

A class to represent the special case values for write_concern::nodes.

See also
https://docs.mongodb.com/manual/reference/write-concern/#w-option

Member Function Documentation

◆ acknowledge_level() [1/2]

level mongocxx::write_concern::acknowledge_level ( ) const

Gets the current acknowledgment level.

See also
https://docs.mongodb.com/manual/reference/write-concern/#w-option
Returns
The acknowledgment level.

◆ acknowledge_level() [2/2]

void mongocxx::write_concern::acknowledge_level ( level  confirm_level)

Sets the acknowledge level.

See also
https://docs.mongodb.com/manual/reference/write-concern/#w-option
Parameters
confirm_levelEither level::k_unacknowledged, level::k_acknowledged, level::k_default, or level::k_majority.
Note
the acknowledge level of level::k_tag is set automatically when a tag is set.
Warning
Setting this to level::k_unacknowledged disables write acknowledgment and all other write concern options.
Unacknowledged writes using dollar-prefixed or dotted keys may be silently rejected by pre-5.0 servers.
Exceptions
Throwsmongocxx::exception for setting a tag acknowledge level. Use tag() instead.

◆ is_acknowledged()

bool mongocxx::write_concern::is_acknowledged ( ) const

Gets whether this write_concern requires an acknowledged write.

Returns
Whether this write concern requires an acknowledged write.

◆ journal() [1/2]

bool mongocxx::write_concern::journal ( ) const

Gets the current status of the journal parameter.

Returns
true if journal is required, false if not.

◆ journal() [2/2]

void mongocxx::write_concern::journal ( bool  journal)

Sets the journal parameter for this write concern.

Parameters
journalIf true confirms that the mongod instance has written the data to the on-disk journal before reporting a write operations was successful. This ensures that data is not lost if the mongod instance shuts down unexpectedly.

◆ majority() [1/2]

bool mongocxx::write_concern::majority ( ) const

Gets whether the majority of nodes is currently required by this write_concern.

Returns
The current majority setting.

◆ majority() [2/2]

void mongocxx::write_concern::majority ( std::chrono::milliseconds  timeout)

Requires that a majority of the nodes in a replica set acknowledge a write operation before it is considered a success.

Parameters
timeoutThe amount of time to wait before the write operation times out if it cannot reach the majority of nodes in the replica set. If the value is zero, then no timeout is set.
Exceptions
mongocxx::logic_errorfor an invalid timeout value.

◆ nodes() [1/2]

stdx::optional<std::int32_t> mongocxx::write_concern::nodes ( ) const

Gets the current number of nodes that this write_concern requires operations to reach.

This value will be unset if the acknowledge_level is set to majority, default, or tag.

This is unset by default.

See also
https://docs.mongodb.com/manual/reference/write-concern/#w-option
Returns
The number of required nodes.

◆ nodes() [2/2]

void mongocxx::write_concern::nodes ( std::int32_t  confirm_from)

Sets the number of nodes that are required to acknowledge the write before the operation is considered successful.

Write operations will block until they have been replicated to the specified number of servers in a replica set.

Parameters
confirm_fromThe number of replica set nodes that must acknowledge the write.
Warning
Setting the number of nodes to 0 disables write acknowledgment and all other write concern options.
Setting the number of nodes required to an amount greater than the number of available nodes will cause writes using this write concern to block forever if no timeout is set.

◆ tag() [1/2]

stdx::optional<std::string> mongocxx::write_concern::tag ( ) const

Gets the current getLastErrorMode that is required by this write_concern.

Returns
The current getLastErrorMode.

◆ tag() [2/2]

void mongocxx::write_concern::tag ( stdx::string_view  tag)

Sets the name representing the server-side getLastErrorMode entry containing the list of nodes that must acknowledge a write operation before it is considered a success.

Note
the acknowledge level of level::k_tag is set automatically when a tag is set.
Parameters
tagThe string representing on of the "getLastErrorModes" in the replica set configuration.

◆ timeout() [1/2]

std::chrono::milliseconds mongocxx::write_concern::timeout ( ) const

Gets the current timeout for this write_concern.

Returns
Current timeout in milliseconds.

◆ timeout() [2/2]

void mongocxx::write_concern::timeout ( std::chrono::milliseconds  timeout)

Sets an upper bound on the time a write concern can take to be satisfied.

If the write concern cannot be satisfied within the timeout, the operation is considered a failure.

Parameters
timeoutThe timeout (in milliseconds) for this write concern. If the value is zero, then no timeout is set.
Exceptions
mongocxx::logic_errorfor an invalid timeout value.

◆ to_document()

bsoncxx::document::value mongocxx::write_concern::to_document ( ) const

Gets the document form of this write_concern.

Returns
Document representation of this write_concern.

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