Update outdated documentation

Author: groue

GRDB/Core/Cursor.swift

@@ -21,8 +21,9 @@ extension RangeReplaceableCollection {
     /// - parameter cursor: The cursor whose elements feed the collection.
     public init<C: Cursor>(_ cursor: C) throws where C.Element == Element {
         self.init()
-        // Use `forEach` in order to deal with <https://github.com/groue/GRDB.swift/issues/1124>.
-        // See `Statement.forEachStep(_:)` for more information.
+        // Prefer `forEach` over `next()` looping, as a slight performance
+        // improvement due to the single `sqlite3_stmt_busy` check for
+        // database cursors.
         try cursor.forEach { append($0) }
     }
 
@@ -38,6 +39,9 @@ extension RangeReplaceableCollection {
     public init<C: Cursor>(_ cursor: C, minimumCapacity: Int) throws where C.Element == Element {
         self.init()
         reserveCapacity(minimumCapacity)
+        // Prefer `forEach` over `next()` looping, as a slight performance
+        // improvement due to the single `sqlite3_stmt_busy` check for
+        // database cursors.
         try cursor.forEach { append($0) }
     }
 }
@@ -58,6 +62,9 @@ extension Dictionary {
     throws where Value == [C.Element]
     {
         self.init()
+        // Prefer `forEach` over `next()` looping, as a slight performance
+        // improvement due to the single `sqlite3_stmt_busy` check for
+        // database cursors.
         try cursor.forEach { value in
             try self[keyForValue(value), default: []].append(value)
         }
@@ -84,6 +91,9 @@ extension Dictionary {
     throws where Value == [C.Element]
     {
         self.init(minimumCapacity: minimumCapacity)
+        // Prefer `forEach` over `next()` looping, as a slight performance
+        // improvement due to the single `sqlite3_stmt_busy` check for
+        // database cursors.
         try cursor.forEach { value in
             try self[keyForValue(value), default: []].append(value)
         }
@@ -106,6 +116,9 @@ extension Dictionary {
     throws where C.Element == (Key, Value)
     {
         self.init()
+        // Prefer `forEach` over `next()` looping, as a slight performance
+        // improvement due to the single `sqlite3_stmt_busy` check for
+        // database cursors.
         try keysAndValues.forEach { key, value in
             if updateValue(value, forKey: key) != nil {
                 fatalError("Duplicate values for key: '\(String(describing: key))'")
@@ -135,6 +148,9 @@ extension Dictionary {
     throws where C.Element == (Key, Value)
     {
         self.init(minimumCapacity: minimumCapacity)
+        // Prefer `forEach` over `next()` looping, as a slight performance
+        // improvement due to the single `sqlite3_stmt_busy` check for
+        // database cursors.
         try keysAndValues.forEach { key, value in
             if updateValue(value, forKey: key) != nil {
                 fatalError("Duplicate values for key: '\(String(describing: key))'")
@@ -153,6 +169,9 @@ extension Set {
     /// - parameter cursor: A cursor of values to gather into a set.
     public init<C: Cursor>(_ cursor: C) throws where C.Element == Element {
         self.init()
+        // Prefer `forEach` over `next()` looping, as a slight performance
+        // improvement due to the single `sqlite3_stmt_busy` check for
+        // database cursors.
         try cursor.forEach { insert($0) }
     }
 
@@ -168,6 +187,9 @@ extension Set {
     ///   storage buffer.
     public init<C: Cursor>(_ cursor: C, minimumCapacity: Int) throws where C.Element == Element {
         self.init(minimumCapacity: minimumCapacity)
+        // Prefer `forEach` over `next()` looping, as a slight performance
+        // improvement due to the single `sqlite3_stmt_busy` check for
+        // database cursors.
         try cursor.forEach { insert($0) }
     }
 }

GRDB/Core/Statement.swift

@@ -316,24 +316,15 @@ public final class Statement {
 
     /// Calls the given closure after each successful call to `sqlite3_step()`.
     ///
-    /// Unlike multiple calls to `step(_:)`, this method is able to deal with
-    /// statements that need a specific authorizer.
-    ///
-    /// That's how we deal with TransactionObservers that observe deletion:
-    /// the authorizer prevents the truncate optimization
-    /// <https://www.sqlite.org/lang_delete.html#the_truncate_optimization>.
-    ///
-    /// That's also how we deal with <https://github.com/groue/GRDB.swift/issues/1124>,
-    /// in four steps:
-    ///
-    /// 1. `T.fetchAll(...)` calls `Array(T.fetchCursor(...))`
-    /// 2. `Array(T.fetchCursor(...))` calls `Cursor.forEach(...)`
-    /// 3. `DatabaseCursor.forEach(...)` calls `Statement.forEachStep(...)`
-    /// 4. `Statement.forEachStep(...)` deals with the eventual authorizer.
+    /// This method is slighly faster than calling `step(_:)` repeatedly, due
+    /// to the single `sqlite3_stmt_busy` check.
     @usableFromInline
     func forEachStep(_ body: (SQLiteStatement) throws -> Void) throws {
         SchedulingWatchdog.preconditionValidQueue(database)
-        try database.statementWillExecute(self)
+        
+        if sqlite3_stmt_busy(sqliteStatement) == 0 {
+            try database.statementWillExecute(self)
+        }
 
         while true {
             switch sqlite3_step(sqliteStatement) {
@@ -349,12 +340,8 @@ public final class Statement {
     }
 
     /// Calls the given closure after one successful call to `sqlite3_step()`.
-    ///
-    /// This method is unable to deal with statements that need a specific
-    /// authorizer. See `forEachStep(_:)`.
     @usableFromInline
-    func step<Element>(_ body: (SQLiteStatement) throws -> Element) throws -> Element? {
-        // This check takes 0 time when profiled. It is, practically speaking, free.
+    func step<T>(_ body: (SQLiteStatement) throws -> T) throws -> T? {
         if sqlite3_stmt_busy(sqliteStatement) == 0 {
             try database.statementWillExecute(self)
         }
@@ -439,9 +426,8 @@ extension DatabaseCursor {
         return nil
     }
 
-    // Specific implementation of `forEach` in order to deal with
-    // <https://github.com/groue/GRDB.swift/issues/1124>.
-    // See `Statement.forEachStep(_:)` for more information.
+    /// Specific implementation of `forEach`, for a slight performance
+    /// improvement due to the single `sqlite3_stmt_busy` check.
     @inlinable
     public func forEach(_ body: (Element) throws -> Void) throws {
         if _isDone { return }

GRDB/Record/FetchableRecord.swift

@@ -196,8 +196,6 @@ extension FetchableRecord {
         adapter: RowAdapter? = nil)
     throws -> [Self]
     {
-        // Use Array initializer in order to deal with <https://github.com/groue/GRDB.swift/issues/1124>.
-        // See `Statement.forEachStep(_:)` for more information.
         try Array(fetchCursor(statement, arguments: arguments, adapter: adapter))
     }