MongoCursor
public class MongoCursor<T> : CursorProtocol where T : Decodable, T : Encodable
A MongoDB cursor.
-
The ID used by the server to track the cursor over time. If all of the cursor’s results were returnable in a single batch, or if the cursor contained no results, this value will be nil.
Declaration
Swift
public let id: Int64?
-
Indicates whether this cursor has the potential to return more data.
This method is mainly useful if this cursor is tailable, since in that case
tryNext
may return more results even after returningnil
.If this cursor is non-tailable, it will always be dead after either
tryNext
returnsnil
or a non-DecodingError
error.This cursor will be dead after
next
returnsnil
or a non-DecodingError
error, regardless of theMongoCursorType
.This cursor may still be alive after
next
ortryNext
returns aDecodingError
.Warning
If this cursor is alive when it goes out of scope, it will leak resources. To ensure it is dead before it leaves scope, invokeMongoCursor.kill(...)
on it.Declaration
Swift
public func isAlive() -> EventLoopFuture<Bool>
-
Attempt to get the next
T
from the cursor, returningnil
if there are no results.If this cursor is tailable, this method may be called repeatedly while
isAlive
is true to retrieve new data.If this cursor is a tailable await cursor, it will wait for results server side for a maximum of
maxAwaitTimeMS
before evaluating tonil
. This option can be configured via options passed to the method that created this cursor (e.g. themaxAwaitTimeMS
option on theFindOptions
passed tofind
).Note: You must not call any cursor methods besides
kill
andisAlive
while the future returned from this method is unresolved. Doing so will result in undefined behavior.Declaration
Swift
public func tryNext() -> EventLoopFuture<T?>
Return Value
An
EventLoopFuture<T?>
containing the nextT
in this cursor, an error if one occurred, ornil
if there was no data.If the future evaluates to an error, it is likely one of the following:
MongoError.CommandError
if an error occurs while fetching more results from the server.MongoError.LogicError
if this function is called after the cursor has died.MongoError.LogicError
if this function is called and the session associated with this cursor is inactive.MongoError.LogicError
if this cursor’s parent client has already been closed.DecodingError
if an error occurs decoding the server’s response.
-
Get the next
T
from the cursor.If this cursor is tailable, this method will continue polling until a non-empty batch is returned from the server or the cursor is closed.
A thread from the driver’s internal thread pool will be occupied until the returned future is completed, so performance degradation is possible if the number of polling cursors is too close to the total number of threads in the thread pool. To configure the total number of threads in the pool, set the
MongoClientOptions.threadPoolSize
option during client creation.Note: You must not call any cursor methods besides
kill
andisAlive
while the future returned from this method is unresolved. Doing so will result in undefined behavior.If the future fails, the error is likely one of the following: -
MongoError.CommandError
if an error occurs while fetching more results from the server. -MongoError.LogicError
if this function is called after the cursor has died. -MongoError.LogicError
if this function is called and the session associated with this cursor is inactive. -DecodingError
if an error occurs decoding the server’s response.Declaration
Swift
public func next() -> EventLoopFuture<T?>
Return Value
An
EventLoopFuture<T?>
evaluating to the nextT
in this cursor, ornil
if the cursor is exhausted. If the underlying cursor is tailable, the future will not resolve until data is returned (potentially after multiple requests to the server), the cursor is closed, or an error occurs. -
Consolidate the currently available results of the cursor into an array of type
T
.If this cursor is not tailable, this method will exhaust it.
If this cursor is tailable,
toArray
will only fetch the currently available results, and it may return more data if it is called again while the cursor is still alive.Note: You must not call any cursor methods besides
kill
andisAlive
while the future returned from this method is unresolved. Doing so will result in undefined behavior.Declaration
Swift
public func toArray() -> EventLoopFuture<[T]>
Return Value
An
EventLoopFuture<[T]>
evaluating to the results currently available in this cursor, or an error.If the future evaluates to an error, that error is likely one of the following:
MongoError.CommandError
if an error occurs while fetching more results from the server.MongoError.LogicError
if this function is called after the cursor has died.MongoError.LogicError
if this function is called and the session associated with this cursor is inactive.DecodingError
if an error occurs decoding the server’s responses.
-
Calls the provided closure with each element in the cursor.
If the cursor is not tailable, this method will exhaust it, calling the closure with every document.
If the cursor is tailable, the method will call the closure with each new document as it arrives.
A thread from the driver’s internal thread pool will be occupied until the returned future is completed, so performance degradation is possible if the number of polling cursors is too close to the total number of threads in the thread pool. To configure the total number of threads in the pool, set the
MongoClientOptions.threadPoolSize
option during client creation.Note: You must not call any cursor methods besides
kill
andisAlive
while the future returned from this method is unresolved. Doing so will result in undefined behavior.Declaration
Swift
public func forEach(_ body: @escaping (T) throws -> Void) -> EventLoopFuture<Void>
Return Value
An
EventLoopFuture<Void>
which will succeed when the end of the cursor is reached, or in the case of a tailable cursor, when the cursor is killed viakill
.If the future evaluates to an error, that error is likely one of the following:
MongoError.CommandError
if an error occurs while fetching more results from the server.MongoError.LogicError
if this function is called after the cursor has died.MongoError.LogicError
if this function is called and the session associated with this cursor is inactive.DecodingError
if an error occurs decoding the server’s responses.
-
Kill this cursor.
This method MAY be called even if there are unresolved futures created from other
MongoCursor
methods.This method MAY be called if the cursor is already dead. It will have no effect.
Warning
If this cursor is alive when it goes out of scope, it will leak resources. To ensure it is dead before it leaves scope, invoke this method.
Declaration
Swift
public func kill() -> EventLoopFuture<Void>
Return Value
An
EventLoopFuture
that evaluates when the cursor has completed closing. This future should not fail.