Merge pull request groue#1253 from george-signal/george-signal/optional-memory-management

Make memory management optional.

Author: groue

GRDB/Core/Configuration.swift

@@ -275,7 +275,15 @@ public struct Configuration {
     ///
     /// Default: nil
     public var writeTargetQueue: DispatchQueue? = nil
-    
+
+#if os(iOS)
+    /// Sets whether GRDB will release memory when entering the background or
+    /// upon receiving a memory warning in iOS.
+    ///
+    /// Default: true
+    public var automaticMemoryManagement = true
+#endif
+
     // MARK: - Factory Configuration
 
     /// Creates a factory configuration

GRDB/Core/Database.swift

@@ -1184,7 +1184,8 @@ public final class Database: CustomStringConvertible, CustomDebugStringConvertib
 
     // MARK: - Memory Management
 
-    func releaseMemory() {
+    public func releaseMemory() {
+        SchedulingWatchdog.preconditionValidQueue(self)
         sqlite3_db_release_memory(sqliteConnection)
         schemaCache.clear()
         internalStatementCache.clear()

GRDB/Core/DatabasePool.swift

@@ -103,7 +103,9 @@ public final class DatabasePool: DatabaseWriter {
         // Be a nice iOS citizen, and don't consume too much memory
         // See https://github.com/groue/GRDB.swift/#memory-management
         #if os(iOS)
-        setupMemoryManagement()
+        if configuration.automaticMemoryManagement {
+            setupMemoryManagement()
+        }
         #endif
     }
 
@@ -154,13 +156,6 @@ public final class DatabasePool: DatabaseWriter {
 
         return configuration
     }
-    
-    /// Blocks the current thread until all database connections have
-    /// executed the *body* block.
-    fileprivate func forEachConnection(_ body: (Database) -> Void) {
-        writer.sync(body)
-        readerPool?.forEach { $0.sync(body) }
-    }
 }
 
 #if swift(>=5.6) && canImport(_Concurrency)
@@ -172,19 +167,49 @@ extension DatabasePool {
 
     // MARK: - Memory management
 
-    /// Free as much memory as possible.
+    /// Frees as much memory as possible, by disposing non-essential memory from
+    /// the writer connection, and closing all reader connections.
+    ///
+    /// This method is synchronous, and blocks the current thread until all
+    /// database accesses are completed.
     ///
-    /// This method blocks the current thread until all database accesses
-    /// are completed.
+    /// - warning: This method can prevent concurrent reads from executing,
+    ///   until it returns. Prefer ``releaseMemoryEventually()`` if you intend
+    ///   to keep on using the database while releasing memory.
     public func releaseMemory() {
         // Release writer memory
         writer.sync { $0.releaseMemory() }
-        // Release readers memory by closing all connections
+        
+        // Release readers memory by closing all connections.
+        //
+        // We must use a barrier in order to guarantee that memory has been
+        // freed (reader connections closed) when the method exits, as
+        // documented.
+        //
+        // Without the barrier, connections would only close _eventually_ (after
+        // their eventual concurrent jobs have completed).
         readerPool?.barrier {
             readerPool?.removeAll()
         }
     }
 
+    /// Eventually frees as much memory as possible, by disposing non-essential
+    /// memory from the writer connection, and closing all reader connections.
+    ///
+    /// Unlike ``releaseMemory()``, this method does not prevent concurrent
+    /// database accesses when it is executing. But it does not notify when
+    /// non-essential memory has been freed.
+    public func releaseMemoryEventually() {
+        // Release readers memory by eventually closing all reader connections
+        // (they will close after their current jobs have completed).
+        readerPool?.removeAll()
+        
+        // Release writer memory eventually.
+        writer.async { db in
+            db.releaseMemory()
+        }
+    }
+    
     #if os(iOS)
     /// Listens to UIApplicationDidEnterBackgroundNotification and
     /// UIApplicationDidReceiveMemoryWarningNotification in order to release
@@ -216,22 +241,28 @@ extension DatabasePool {
 
         let task: UIBackgroundTaskIdentifier = application.beginBackgroundTask(expirationHandler: nil)
         if task == .invalid {
-            // Perform releaseMemory() synchronously.
+            // Release memory synchronously
             releaseMemory()
         } else {
-            // Perform releaseMemory() asynchronously.
-            DispatchQueue.global().async {
-                self.releaseMemory()
+            // Release memory eventually.
+            //
+            // We don't know when reader connections will be closed (because
+            // they may be currently in use), so we don't quite know when
+            // reader memory will be freed (which would be the ideal timing for
+            // ending our background task).
+            //
+            // So let's just end the background task after the writer connection
+            // has freed its memory. That's better than nothing.
+            releaseMemoryEventually()
+            writer.async { _ in
                 application.endBackgroundTask(task)
             }
         }
     }
 
     @objc
     private func applicationDidReceiveMemoryWarning(_ notification: NSNotification) {
-        DispatchQueue.global().async {
-            self.releaseMemory()
-        }
+        releaseMemoryEventually()
     }
     #endif
 }

GRDB/Core/DatabaseQueue.swift

@@ -43,7 +43,9 @@ public final class DatabaseQueue: DatabaseWriter {
         // Be a nice iOS citizen, and don't consume too much memory
         // See https://github.com/groue/GRDB.swift/#memory-management
         #if os(iOS)
-        setupMemoryManagement()
+        if configuration.automaticMemoryManagement {
+            setupMemoryManagement()
+        }
         #endif
     }
 
@@ -117,21 +119,21 @@ extension DatabaseQueue {
 
         let task: UIBackgroundTaskIdentifier = application.beginBackgroundTask(expirationHandler: nil)
         if task == .invalid {
-            // Perform releaseMemory() synchronously.
+            // Release memory synchronously
             releaseMemory()
         } else {
-            // Perform releaseMemory() asynchronously.
-            DispatchQueue.global().async {
-                self.releaseMemory()
+            // Release memory asynchronously
+            writer.async { db in
+                db.releaseMemory()
                 application.endBackgroundTask(task)
             }
         }
     }
 
     @objc
     private func applicationDidReceiveMemoryWarning(_ notification: NSNotification) {
-        DispatchQueue.global().async {
-            self.releaseMemory()
+        writer.async { db in
+            db.releaseMemory()
         }
     }
     #endif

README.md

@@ -7718,12 +7718,36 @@ dbPool.releaseMemory()
 
 This method blocks the current thread until all current database accesses are completed, and the memory collected.
 
+> :warning: **Warning**: If `DatabasePool.releaseMemory()` is called while a long read is performed concurrently, then no other read access will be possible until this long read has completed, and the memory has been released. If this does not suit your application needs, look for the asynchronous options below:
+
+You can release memory in an asynchronous way as well:
+
+```swift
+// On a DatabaseQueue
+dbQueue.asyncWriteWithoutTransaction { db in
+    db.releaseMemory()
+}
+
+// On a DatabasePool
+dbPool.releaseMemoryEventually()
+```
+
+`DatabasePool.releaseMemoryEventually()` does not block the current thread, and does not prevent concurrent database accesses. In exchange for this convenience, you don't know when memory has been freed.
+
 
 ### Memory Management on iOS
 
 **The iOS operating system likes applications that do not consume much memory.**
 
-[Database queues](#database-queues) and [pools](#database-pools) automatically call the `releaseMemory` method when the application receives a memory warning, and when the application enters background.
+[Database queues](#database-queues) and [pools](#database-pools) automatically free non-essential memory when the application receives a memory warning, and when the application enters background.
+
+You can opt out of this automatic memory management:
+
+```swift
+var config = Configuration()
+config.automaticMemoryManagement = false
+let dbQueue = try DatabaseQueue(path: dbPath, configuration: config) // or DatabasePool
+```
 
 
 ## Data Protection

Tests/GRDBTests/DatabasePoolReleaseMemoryTests.swift

@@ -41,6 +41,85 @@ class DatabasePoolReleaseMemoryTests: GRDBTestCase {
         XCTAssertEqual(openConnectionCount, 0)
     }
 
+#if os(iOS)
+    func testDatabasePoolReleasesMemoryOnPressureEvent() throws {
+        // Create a database pool, and expect a reader connection to be closed
+        let expectation = self.expectation(description: "Reader connection closed")
+        
+        var configuration = Configuration()
+        configuration.SQLiteConnectionWillClose = { conn in
+            if sqlite3_db_readonly(conn, nil) != 0 {
+                expectation.fulfill()
+            }
+        }
+        let dbPool = try makeDatabasePool(configuration: configuration)
+        
+        // Precondition: there is one reader.
+        try dbPool.read { _ in }
+        
+        // Simulate memory warning.
+        NotificationCenter.default.post(
+            name: NSNotification.Name(rawValue: "UIApplicationDidReceiveMemoryWarningNotification"),
+            object: nil)
+        
+        // Postcondition: reader connection was closed
+        withExtendedLifetime(dbPool) { _ in
+            waitForExpectations(timeout: 0.5)
+        }
+    }
+
+    func testDatabasePoolDoesNotReleaseMemoryOnPressureEventIfDisabled() throws {
+        // Create a database pool, and do not expect any reader connection to be closed
+        let expectation = self.expectation(description: "Reader connection closed")
+        expectation.isInverted = true
+        
+        var configuration = Configuration()
+        configuration.automaticMemoryManagement = false
+        configuration.SQLiteConnectionWillClose = { conn in
+            if sqlite3_db_readonly(conn, nil) != 0 {
+                expectation.fulfill()
+            }
+        }
+        let dbPool = try makeDatabasePool(configuration: configuration)
+        
+        // Precondition: there is one reader.
+        try dbPool.read { _ in }
+        
+        // Simulate memory warning.
+        NotificationCenter.default.post(
+            name: NSNotification.Name(rawValue: "UIApplicationDidReceiveMemoryWarningNotification"),
+            object: nil)
+        
+        // Postcondition: no reader connection was closed
+        withExtendedLifetime(dbPool) { _ in
+            waitForExpectations(timeout: 0.5)
+        }
+    }
+    
+    // Regression test for <https://github.com/groue/GRDB.swift/pull/1253#issuecomment-1177166630>
+    func testDatabasePoolDoesNotPreventConcurrentReadsOnPressureEvent() throws {
+        let dbPool = try makeDatabasePool()
+        
+        // Start a read that blocks
+        let semaphore = DispatchSemaphore(value: 0)
+        dbPool.asyncRead { _ in
+            semaphore.wait()
+        }
+        
+        // Simulate memory warning.
+        NotificationCenter.default.post(
+            name: NSNotification.Name(rawValue: "UIApplicationDidReceiveMemoryWarningNotification"),
+            object: nil)
+        
+        // Make sure we can read
+        try dbPool.read { _ in }
+        
+        // Cleanup
+        semaphore.signal()
+    }
+
+#endif
+
     // TODO: fix flaky test
 //    func testDatabasePoolReleaseMemoryClosesReaderConnections() throws {
 //        let countQueue = DispatchQueue(label: "GRDB")