SWIFT-853 Clarify requirements for when when cursors/change streams need to be killed (#488)

Author: patrickfreed

Sources/MongoSwift/ChangeStream.swift

@@ -108,7 +108,19 @@ public class ChangeStream<T: Codable>: CursorProtocol {
         }
     }
 
-    /// Indicates whether this change stream has the potential to return more data.
+    /**
+     * 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.
+     */
     public func isAlive() -> EventLoopFuture<Bool> {
         self.client.operationExecutor.execute {
             self.wrappedCursor.isAlive
@@ -234,9 +246,13 @@ public class ChangeStream<T: Codable>: CursorProtocol {
     /**
      * Kill this change stream.
      *
-     * This method MUST be called before this change stream goes out of scope to prevent leaking resources.
-     * This method may be called even if there are unresolved futures created from other `ChangeStream` methods.
-     * This method will have no effect if the change stream is already dead.
+     * 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.
      *
      * - Returns:
      *   An `EventLoopFuture` that evaluates when the change stream has completed closing. This future should not fail.

Sources/MongoSwift/MongoClient.swift

@@ -475,6 +475,10 @@ public class MongoClient {
      *   - options: An optional `ChangeStreamOptions` to use when constructing the change stream.
      *   - session: An optional `ClientSession` to use with this change stream.
      *
+     * - Warning:
+     *    If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the
+     *    change stream is dead before it leaves scope, invoke `ChangeStream.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<ChangeStream>`. On success, contains a `ChangeStream` watching all collections in this
      *    deployment.
@@ -512,6 +516,10 @@ public class MongoClient {
      *   - withFullDocumentType: The type that the `fullDocument` field of the emitted `ChangeStreamEvent`s will be
      *                           decoded to.
      *
+     * - Warning:
+     *    If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the
+     *    change stream is dead before it leaves scope, invoke `ChangeStream.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<ChangeStream>`. On success, contains a `ChangeStream` watching all collections in this
      *    deployment.
@@ -554,6 +562,10 @@ public class MongoClient {
      *   - withEventType: The type that the entire change stream response will be decoded to and that will be returned
      *                    when iterating through the change stream.
      *
+     * - Warning:
+     *    If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the
+     *    change stream is dead before it leaves scope, invoke `ChangeStream.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<ChangeStream>`. On success, contains a `ChangeStream` watching all collections in this
      *    deployment.

Sources/MongoSwift/MongoCollection+ChangeStreams.swift

@@ -12,6 +12,10 @@ extension MongoCollection {
      *   - options: An optional `ChangeStreamOptions` to use when constructing the change stream.
      *   - session: An optional `ClientSession` to use with this change stream.
      *
+     * - Warning:
+     *    If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the
+     *    change stream is dead before it leaves scope, invoke `ChangeStream.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<ChangeStream>`. On success, contains a `ChangeStream` watching this collection.
      *
@@ -46,6 +50,10 @@ extension MongoCollection {
      *   - withFullDocumentType: The type that the `fullDocument` field of the emitted `ChangeStreamEvent`s will be
      *                           decoded to.
      *
+     * - Warning:
+     *    If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the
+     *    change stream is dead before it leaves scope, invoke `ChangeStream.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<ChangeStream>`. On success, contains a `ChangeStream` watching this collection.
      *
@@ -85,6 +93,10 @@ extension MongoCollection {
      *   - withEventType: The type that the entire change stream response will be decoded to and that will be returned
      *                    when iterating through the change stream.
      *
+     * - Warning:
+     *    If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the
+     *    change stream is dead before it leaves scope, invoke `ChangeStream.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<ChangeStream>`. On success, contains a `ChangeStream` watching this collection.
      *

Sources/MongoSwift/MongoCollection+Indexes.swift

@@ -381,6 +381,10 @@ extension MongoCollection {
      * - Parameters:
      *   - session: Optional `ClientSession` to use when executing this command
      *
+     * - Warning:
+     *    If the returned cursor is alive when it goes out of scope, it will leak resources. To ensure the
+     *    cursor is dead before it leaves scope, invoke `MongoCursor.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<MongoCursor<IndexModel>>`. On success, contains a cursor over the indexes.
      *

Sources/MongoSwift/MongoCollection+Read.swift

@@ -6,6 +6,10 @@ extension MongoCollection {
     /**
      * Finds the documents in this collection which match the provided filter.
      *
+     * - Warning:
+     *    If the returned cursor is alive when it goes out of scope, it will leak resources. To ensure the cursor
+     *    is dead before it leaves scope, invoke `MongoCursor.kill(...)` on it.
+     *
      * - Parameters:
      *   - filter: A `BSONDocument` that should match the query
      *   - options: Optional `FindOptions` to use when executing the command
@@ -66,6 +70,10 @@ extension MongoCollection {
      *   - options: Optional `AggregateOptions` to use when executing the command
      *   - session: Optional `ClientSession` to use when executing this command
      *
+     * - Warning:
+     *    If the returned cursor is alive when it goes out of scope, it will leak resources. To ensure the cursor
+     *    is dead before it leaves scope, invoke `MongoCursor.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<MongoCursor<CollectionType>`. On success, contains a cursor over the resulting documents.
      *

Sources/MongoSwift/MongoCursor.swift

@@ -99,9 +99,17 @@ public class MongoCursor<T: Codable>: CursorProtocol {
      * 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 as soon as either `tryNext` returns `nil` or an error.
+     * 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 as soon as `next` returns `nil` or an error, regardless of the `MongoCursorType`.
+     * 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.
      */
     public func isAlive() -> EventLoopFuture<Bool> {
         self.client.operationExecutor.execute {
@@ -231,8 +239,13 @@ public class MongoCursor<T: Codable>: CursorProtocol {
     /**
      * Kill this cursor.
      *
-     * This method MUST be called before this cursor goes out of scope to prevent leaking resources.
-     * This method may be called even if there are unresolved futures created from other `MongoCursor` methods.
+     * 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.
      *
      * - Returns:
      *   An `EventLoopFuture` that evaluates when the cursor has completed closing. This future should not fail.

Sources/MongoSwift/MongoDatabase.swift

@@ -234,6 +234,10 @@ public struct MongoDatabase {
      *   - options: Optional `ListCollectionsOptions` to use when executing this command
      *   - session: Optional `ClientSession` to use when executing this command
      *
+     * - Warning:
+     *    If the returned cursor is alive when it goes out of scope, it will leak resources. To ensure the cursor
+     *    is dead before it leaves scope, invoke `MongoCursor.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<MongoCursor<CollectionSpecification>>` containing a cursor over the collections.
      *
@@ -352,6 +356,10 @@ public struct MongoDatabase {
      *   - options: An optional `ChangeStreamOptions` to use when constructing the change stream.
      *   - session: An optional `ClientSession` to use with this change stream.
      *
+     * - Warning:
+     *    If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the
+     *    change stream is dead before it leaves scope, invoke `ChangeStream.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<ChangeStream>`. On success, contains a `ChangeStream` watching all collections in this
      *    database.
@@ -389,6 +397,10 @@ public struct MongoDatabase {
      *   - withFullDocumentType: The type that the `fullDocument` field of the emitted `ChangeStreamEvent`s will be
      *                           decoded to.
      *
+     * - Warning:
+     *    If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the
+     *    change stream is dead before it leaves scope, invoke `ChangeStream.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<ChangeStream>`. On success, contains a `ChangeStream` watching all collections in this
      *    database.
@@ -431,6 +443,10 @@ public struct MongoDatabase {
      *   - withEventType: The type that the entire change stream response will be decoded to and that will be returned
      *                    when iterating through the change stream.
      *
+     * - Warning:
+     *    If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the
+     *    change stream is dead before it leaves scope, invoke `ChangeStream.kill(...)` on it.
+     *
      * - Returns:
      *    An `EventLoopFuture<ChangeStream>`. On success, contains a `ChangeStream` watching all collections in this
      *    database.

Sources/MongoSwiftSync/ChangeStream.swift

@@ -26,8 +26,11 @@ public class ChangeStream<T: Codable>: CursorProtocol {
     /**
      * Indicates whether this change stream has the potential to return more data.
      *
-     * This change stream will be dead if `next` returns `nil` or an error. It will also be dead if `tryNext` returns
-     * an error, but will still be alive if `tryNext` returns `nil`.
+     * 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.
      */
     public func isAlive() -> Bool {
         do {

Sources/MongoSwiftSync/MongoCursor.swift

@@ -19,9 +19,13 @@ public class MongoCursor<T: Codable>: CursorProtocol {
      * 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 as soon as either `tryNext` returns `nil` or an error.
+     * 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 as soon as `next` returns `nil` or an error, regardless of the `MongoCursorType`.
+     * 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`.
      */
     public func isAlive() -> Bool {
         do {