[CXX-2441] Add example of iterating change stream indefinitely Created: 03/Feb/22  Updated: 28/Oct/23  Resolved: 07/Mar/23

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

Type: Improvement Priority: Minor - P4
Reporter: Kevin Albertson Assignee: Kevin Albertson
Resolution: Fixed Votes: 0
Labels: neweng
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to CXX-2278 [ChangeStream] Why does iterating cha... Closed
is related to CXX-2435 Why does change stream end when more ... Closed
Quarter: FY24Q1

 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.



 Comments   
Comment by Githook User [ 07/Mar/23 ]

Author:

{'name': 'Kevin Albertson', 'email': 'kevin.albertson@mongodb.com', 'username': 'kevinAlbs'}

Message: CXX-2441 revise docs and example of change streams (#936)

  • remove unnecessary Travis workaround

The C++ driver no longer tests with Travis

  • iterate change stream indefinitely
  • fix documentation link
  • fix typo
  • revise comment on blocking

If there are documents in the locally cached batch, change_stream::begin()
and increment operators do not block.
They only block if the server is polled.

  • note lifetime of document::view returned by iterator
  • note more notifications can be available by iterating
  • suggest how to produce notifications
Generated at Wed Feb 07 22:05:56 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.