[CXX-2091] Documents ambiguous about error handling Created: 15/Aug/20  Updated: 27/Oct/23  Resolved: 29/Aug/20

Status: Closed
Project: C++ Driver
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major - P3
Reporter: Puya Daravi Assignee: Unassigned
Resolution: Works as Designed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Epic Link: CXX usability improvements
Quarter: FY24Q3

 Description   

Hello. I am looking at `insert`, `update_x` and `delete_x` documentation and it is unclear to me whether:
1- Operation failure throws exception or
2- Operation failure returns a nullopt or
3- In some modes of failure it throws an exception while in other modes it returns a nullopt

Are some errors handled by exception while others are handled by returning a nullopt result? If so then I propose this be clarified in the documentation and to consider having a single mode of error reporting to make error handling easier.

If not please let me know what is the correct way to handle all possible error cases.



 Comments   
Comment by Kevin Albertson [ 29/Aug/20 ]

Hi puya@motionmetrics.com.

For those operations, if an error occurs, a mongocxx::exception::bulk_write_exception is thrown.

try {
    auto result = coll.insert_one(make_document(kvp("a", 1)));
    // If no exception was thrown, result is necessarily set.
} catch (mongocxx::bulk_write_exception& bwe) {
    std::cout << "error occurred" << std::endl;
}  

If an unacknowledged write concern is used, the server does not send back a reply, so stdx::nullopt is returned. A mongocxx::exception::bulk_write_exception could still be returned on a client error (e.g. a socket timeout).

mongocxx::write_concern wc_unacknowledged;
mongocxx::options::insert opts;
opts.write_concern (wc_unacknowledged);
try {
    auto result = coll.insert_one(make_document(kvp("a", 1)), opts);
} catch (mongocxx::bulk_write_exception& bwe) {
    std::cout << "error occurred" << std::endl;
}

So, handling the exception should be the only requirement for checking if the operation succeeded. If using an unacknowledged write concern, the operation could have failed server-side, but using an unacknowledged write concern is opting into that fire-and-forget behavior.

The documentation for insert/update/delete collections functions refers to this behavior, e.g. for collection::insert_one

Returns
The optional result of attempting to perform the insert. If the write concern is unacknowledged, the optional will be disengaged.

Exceptions
mongocxx::bulk_write_exception if the operation fails.

Generated at Wed Feb 07 22:04:51 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.