ChangeStream
public class ChangeStream<T> : CursorProtocol where T : Decodable, T : Encodable
A MongoDB change stream.
-
Indicates whether this change stream has the potential to return more data.
This change stream will be dead after
next
returnsnil
, but it may still be alive aftertryNext
returnsnil
.After either of
next
ortryNext
return a non-DecodingError
error, this change stream will be dead. It may still be alive after either returns aDecodingError
, 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, invokeChangeStream.kill(...)
on it.Declaration
Swift
public func isAlive() -> EventLoopFuture<Bool>
-
The
ResumeToken
associated with the most recent event seen by the change stream.Declaration
Swift
public internal(set) var resumeToken: ResumeToken? { get }
-
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 theChangeStreamOptions
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
andisAlive
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 nextT
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. -
Attempt to get the next
T
from this change stream, returningnil
if there are no results.The change stream will wait server-side for a maximum of
maxAwaitTimeMS
(specified on theChangeStreamOptions
passed to the method that created this change stream) before returningnil
.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
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 change stream, 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 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.
-
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
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 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.
-
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
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 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.
-
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
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 this method.
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.