ChangeStream

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

A MongoDB change stream.

See also

https://docs.mongodb.com/manual/changeStreams/
Show on GitHub

  • Undocumented

    Declaration

    Swift

    public typealias Element = T
    Show on GitHub

  • Indicates whether this change stream has the potential to return more data.

    This change stream will be dead after next returns nil, but it may still be alive after tryNext returns nil.

    After either of next or tryNext return a non-DecodingError error, this change stream will be dead. It may still be alive after either returns a DecodingError, however.

    Warning

    If this change stream is alive when it goes out of scope, it will leak resources. To ensure it is dead before it leaves scope, invoke ChangeStream.kill(...) on it.

    Declaration

    Swift

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

  • The ResumeToken associated with the most recent event seen by the change stream.

    Declaration

    Swift

    public internal(set) var resumeToken: ResumeToken? { get }
    Show on GitHub

  • Get the next T from this change stream.

    This method will continue polling until an event is returned from the server, an error occurs, or the change stream is killed. Each attempt to retrieve results will wait for a maximum of maxAwaitTimeMS (specified on the ChangeStreamOptions passed to the method that created this change stream) before trying again.

    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 change streams 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 change stream methods besides kill and isAlive while the future returned from this method is unresolved. Doing so will result in undefined behavior.

    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 change stream has died. - MongoError.LogicError if this function is called and the session associated with this change stream 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 change stream, nil if the change stream is exhausted, or an error if one occurred. The returned future will not resolve until one of those conditions is met, potentially after multiple requests to the server.

    Show on GitHub

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

    The change stream will wait server-side for a maximum of maxAwaitTimeMS (specified on the ChangeStreamOptions passed to the method that created this change stream) before returning nil.

    This method may be called repeatedly while isAlive is true to retrieve new data.

    Note: You must not call any change stream 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 change stream, 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:

    • MongoError.CommandError if an error occurs while fetching more results from the server.
    • MongoError.LogicError if this function is called after the change stream has died.
    • MongoError.LogicError if this function is called and the session associated with this change stream is inactive.
    • DecodingError if an error occurs decoding the server’s response.
    Show on GitHub

  • Consolidate the currently available results of the change stream into an array of type T.

    Since toArray will only fetch the currently available results, it may return more data if it is called again while the change stream is still alive.

    Note: You must not call any change stream 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 change stream, 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 change stream has died.
    • MongoError.LogicError if this function is called and the session associated with this change stream is inactive.
    • DecodingError if an error occurs decoding the server’s responses.
    Show on GitHub

  • Calls the provided closure with each event in the change stream 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 change streams 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 change stream 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 complete once the change stream is closed or once an error is encountered.

    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 change stream has died.
      • MongoError.LogicError if this function is called and the session associated with this change stream is inactive.
    • DecodingError if an error occurs decoding the server’s responses.
    Show on GitHub

  • Kill this change stream.

    This method MAY be called even if there are unresolved futures created from other ChangeStream methods.

    This method MAY be called if the change stream is already dead. It will have no effect.

    Warning

    On Swift versions and platforms where structured concurrency is not available, if a change stream 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 change stream has completed closing. This future should not fail.

    Show on GitHub

  • Declaration

    Swift

    public typealias AsyncIterator = ChangeStream
    Show on GitHub

  • Declaration

    Swift

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

  • Indicates whether this change stream has the potential to return more data.

    This change stream will be dead after next() returns nil, but it may still be alive after tryNext() returns nil.

    After either of next() or tryNext() throw a non-DecodingError error, this change stream will be dead. It may still be alive after either returns a DecodingError, however.

    Declaration

    Swift

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

  • Get the next T from this change stream.

    This method will continue polling until an event is returned from the server, an error occurs, or the current Task is cancelled. Each attempt to retrieve results will wait for a maximum of maxAwaitTimeMS (specified on the ChangeStreamOptions passed to the method that created this change stream) before trying again.

    We recommend to run change streams in their own Tasks, and to terminate them by cancelling their Tasks.

    Warning

    You must not call any change stream 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 change stream has been exhausted. - MongoError.LogicError if this function is called and the session associated with this change stream 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 change stream, or nil if the change stream is exhausted or the current Task is cancelled. This method will not return until one of those conditions is met, potentially after multiple requests to the server.

    Show on GitHub

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

    The change stream will wait server-side for a maximum of maxAwaitTimeMS (specified on the ChangeStreamOptions passed to the method that created this change stream) before returning nil.

    This method may be called repeatedly while isAlive() is true to retrieve new data.

    Warning

    You must not call any change stream 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 change stream has been exhausted. - MongoError.LogicError if this function is called and the session associated with this change stream 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 change stream, or nil if there is no new data.

    Show on GitHub

  • Consolidate the currently available results of the change stream into an array of type T.

    Since toArray will only fetch the currently available results, it may return more data if it is called again while the change stream is still alive.

    Warning

    You must not call any change stream 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 change stream has been exhausted. - MongoError.LogicError if this function is called and the session associated with this change stream 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 change stream.

    Show on GitHub