MongoCursor

public class MongoCursor<T> : CursorProtocol where T : Decodable, T : Encodable
extension MongoCursor: AsyncSequence, AsyncIteratorProtocol

A MongoDB cursor.

Show on GitHub
  • id

    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?
    Show on GitHub

  • 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 returning nil.

    If this cursor is non-tailable, it will always be dead after either tryNext returns nil or a non-DecodingError error.

    This cursor will be dead after next returns nil or a non-DecodingError error, regardless of the MongoCursorType.

    This cursor may still be alive after next or tryNext returns a DecodingError.

    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 MongoCursor.kill(...) on it.

    Declaration

    Swift

    public func isAlive() -> EventLoopFuture<Bool>
    Show on GitHub

  • Attempt to get the next T from the cursor, returning nil 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 to nil. This option can be configured via options passed to the method that created this cursor (e.g. the maxAwaitTimeMS option on the FindOptions passed to find).

    Note: You must not call any cursor methods besides kill and isAlive 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 next T in this cursor, an error if one occurred, or nil if there was no data.

    If the future evaluates to an error, it is likely one of the following:

    Show on GitHub

  • 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 and isAlive 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 next T in this cursor, or nil 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.

    Show on GitHub

  • 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 and isAlive 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.
    Show on GitHub

  • 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 and isAlive 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 via kill.

    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.
    Show on GitHub

  • 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

    On Swift versions and platforms where structured concurrency is not available, if a cursor is alive when it goes out of scope, it will leak resources. On those Swift versions/platforms, you must invoke this method to ensure resources are properly cleaned up. If structured concurrency is available, it is not necessary to call this method as resources will be cleaned up automatically during deinitialization.

    Declaration

    Swift

    public func kill() -> EventLoopFuture<Void>

    Return Value

    An EventLoopFuture that evaluates when the cursor has completed closing. This future should not fail.

    Show on GitHub

  • Declaration

    Swift

    public typealias AsyncIterator = MongoCursor
    Show on GitHub

  • Declaration

    Swift

    public typealias Element = T
    Show on GitHub

  • Declaration

    Swift

    public func makeAsyncIterator() -> MongoCursor<T>
    Show on GitHub

  • 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 returning nil.

    If this cursor is non-tailable, it will always be dead after either tryNext() returns nil or a non-DecodingError error.

    This cursor will be dead after next() returns nil or throws a non-DecodingError error, regardless of the cursor type.

    This cursor may still be alive after next() or tryNext() throws a DecodingError.

    Declaration

    Swift

    public func isAlive() async throws -> Bool
    Show on GitHub

  • Returns the next T in this cursor, or nil if the cursor is exhausted or the current Task is cancelled.

    If this cursor is tailable, this method will continue polling until a non-empty batch is returned from the server, or until the Task it is running in is cancelled. For this reason, we recommend to run tailable cursors in their own Tasks, and to terminate the cursor if/when needed by canceling the Task.

    Warning

    You must not call any cursor methods besides isAlive() while awaiting the result of this method. Doing so will result in undefined behavior.

    If an error is thrown, 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 been exhausted.
    • MongoError.LogicError if this function is called and the session associated with this cursor has been ended.
    • DecodingError if an error occurs decoding the server’s response to a T.

    Declaration

    Swift

    public func next() async throws -> T?

    Return Value

    The next T in this cursor, or nil if the cursor is exhausted or the current Task is cancelled.

    Show on GitHub

  • Attempt to get the next T from the cursor, returning nil if there are no results.

    If this cursor is tailable, this method may be called repeatedly while isAlive() returns 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 to nil. This option can be configured via options passed to the method that created this cursor (e.g. the maxAwaitTimeMS option on the FindOptions passed to find).

    Warning

    You must not call any cursor methods besides isAlive() while awaiting the result of this method. Doing so will result in undefined behavior.

    If an error is thrown, 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 been exhausted. - MongoError.LogicError if this function is called and the session associated with this cursor has been ended. - DecodingError if an error occurs decoding the server’s response to a T.

    Declaration

    Swift

    public func tryNext() async throws -> T?

    Return Value

    The next T in this cursor, or nil if there is no new data.

    Show on GitHub

  • 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.

    Warning

    You must not call any cursor methods besides isAlive() while awaiting the result of this method. Doing so will result in undefined behavior.

    If an error is thrown, 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 been exhausted. - MongoError.LogicError if this function is called and the session associated with this cursor has been ended. - DecodingError if an error occurs decoding the server’s responses to Ts.

    Declaration

    Swift

    public func toArray() async throws -> [T]

    Return Value

    An T containing the results currently available in this cursor.

    Show on GitHub