Uploaded image for project: 'C++ Driver'
  1. C++ Driver
  2. CXX-2441

Add example of iterating change stream indefinitely

    • Type: Icon: Improvement Improvement
    • Resolution: Fixed
    • Priority: Icon: Minor - P4 Minor - P4
    • 3.8.0
    • Affects Version/s: None
    • Component/s: Documentation

      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.

            Assignee:
            kevin.albertson@mongodb.com Kevin Albertson
            Reporter:
            kevin.albertson@mongodb.com Kevin Albertson
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: