Details
-
Improvement
-
Resolution: Fixed
-
Minor - P4
-
None
Description
Background & Motivation
There have been several questions about how to iterate a change stream to block indefinitely until the next notification or error:
CXX-2435, CXX-2278, and HELP-28966. It is not clear from the documentation how to accomplish this.
Scope
Propose the following improvements to documentation:
1. Add a note in the function comments of change_stream::iterator::operator++
If no notification is available, callers may call change_stream::begin() to check for more notifications.
2. Add a note in the function comments of change_stream::iterator::operator* and change_stream::iterator::operator->:
The returned document::view is valid until the iterator is incremented. The value may be copied to extend its lifetime.
3. Update the example in https://github.com/mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/change_streams.cpp. Change watch_until to resemble the following:
auto cs = db.collection("coll").watch(); // sends one aggregate command. |
auto cs_iter = cs.begin(); // may send getMore if more events are needed. May send aggregate if resume is needed. |
while (true) { |
if (cs_iter == cs.end()) { |
std::cout << "No event yet." << std::endl; |
cs_iter = cs.begin (); // may send getMore if more events are needed. May send aggregate if resume is needed. |
} else { |
bsoncxx::document::view event = *cs_iter;
|
std::cout << "Got event: " << bsoncxx::to_json (event) << std::endl; |
cs_iter++; // may send getMore if more events are needed. May send aggregate if resume is needed. |
}
|
}
|
Waiting for a notification or error is the most common use case.