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; with the latter only the initial find or aggregate may be re-sent. Use the same connection for the whole life of a cursor.
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.
The cursor is always released on the client: the request is not re-sent, cursorsNotFound counts as killed, and a reply that lists the cursor as neither killed nor not found throws Poco::ProtocolException. A second call after a failed kill() sends nothing: the cursor is already released.
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.
The cursor is always released on the client: the request is not re-sent, cursorsNotFound counts as killed, and a reply that lists the cursor as neither killed nor not found throws Poco::ProtocolException. A second call after a failed kill() sends nothing: the cursor is already released.
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.
The getMore request is not re-sent. After next() throws, call kill() and run the query again with a new cursor. After the connection was dropped, getMore may reach another server (CursorNotFound); check responseOk() before treating an inactive cursor as complete.
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