Library: MongoDB
Package: MongoDB
Header: Poco/MongoDB/OpMsgCursor.h
Description
OpMsgCursor is a helper class for querying multiple documents using OpMsgMessage. Once all of the data is read with the cursor (see isActive()) it can't be reused.
USAGE: Supports both Connection and ReplicaSetConnection. When using ReplicaSetConnection, cursor operations benefit from automatic retry and failover on retriable errors.
RESOURCE MANAGEMENT: When a cursor is no longer needed, you should call kill() to release server-side resources. If kill() is not called explicitly, the server will keep the cursor open until it times out.
THREAD SAFETY: This class is NOT thread-safe. A cursor must not be used concurrently from multiple threads. Each thread should have its own cursor instances. The next() method modifies internal state and is not safe for concurrent access.
Inheritance
Direct Base Classes: Document
All Base Classes: Document
Member Summary
Member Functions: batchSize, cursorID, emptyFirstBatch, isActive, kill, next, query, setBatchSize, setEmptyFirstBatch
Inherited Functions: add, addElement, addNewArray, addNewDocument, clear, elementNames, elements, empty, exists, get, getInteger, isType, read, remove, reserve, size, toString, write
Constructors
OpMsgCursor
OpMsgCursor(
const std::string & dbname,
const std::string & collectionName
);
Creates a OpMsgCursor for the given database and collection.
Destructor
~OpMsgCursor 
virtual ~OpMsgCursor();
Destroys the OpMsgCursor.
Member Functions
batchSize
[[nodiscard]]
Int32 batchSize() const noexcept;
Current batch size (zero or negative number indicates default batch size)
cursorID 
[[nodiscard]]
Int64 cursorID() const noexcept;
emptyFirstBatch
[[nodiscard]]
bool emptyFirstBatch() const noexcept;
isActive
[[nodiscard]]
bool isActive() const noexcept;
Is there more data to acquire with this cursor?
kill
void kill(
Connection & connection
);
Kills the cursor and resets its internal state. Call this method when you don't need all documents to release server resources.
kill
void kill(
ReplicaSetConnection & connection
);
Kills the cursor and resets its internal state. Call this method when you don't need all documents to release server resources.
This overload provides automatic retry and failover for replica set deployments.
next
OpMsgMessage & next(
Connection & connection
);
Tries to get the next documents. As long as response message has a cursor ID next can be called to retrieve the next bunch of documents.
The cursor must be killed (see kill()) when not all documents are needed.
next
OpMsgMessage & next(
ReplicaSetConnection & connection
);
Tries to get the next documents. As long as response message has a cursor ID next can be called to retrieve the next bunch of documents.
The cursor must be killed (see kill()) when not all documents are needed.
This overload provides automatic retry and failover for replica set deployments.
query
OpMsgMessage & query();
Returns the associated query.
setBatchSize
void setBatchSize(
Int32 batchSize
) noexcept;
Set non-default batch size
setEmptyFirstBatch
void setEmptyFirstBatch(
bool empty
) noexcept;
Empty first batch is used to get error response faster with little server processing