mirror of
https://github.com/groue/GRDB.swift
synced 2026-11-22 04:00:39 +00:00
Document that async methods can throw CancellationError
This commit is contained in:
1 parent
5fad4fe028
commit
8df18fb82b
4 files changed
+24
-11
No files matched your search
@@ -213,8 +213,9 @@ public protocol DatabaseReader: AnyObject, Sendable {
|
||||
/// later use.
|
||||
///
|
||||
/// - parameter value: A closure which accesses the database.
|
||||
/// - throws: The error thrown by `value`, or any ``DatabaseError`` that
|
||||
/// would happen while establishing the database access.
|
||||
/// - throws: Any ``DatabaseError`` that happens while establishing the
|
||||
/// database access, or the error thrown by `value`, or
|
||||
/// `CancellationError` if the task is cancelled.
|
||||
@available(iOS 13, macOS 10.15, tvOS 13, *)
|
||||
func read<T>(
|
||||
_ value: sending @escaping (Database) throws -> sending T
|
||||
@@ -319,8 +320,9 @@ public protocol DatabaseReader: AnyObject, Sendable {
|
||||
/// - warning: Attempts to write in the database may succeed.
|
||||
///
|
||||
/// - parameter value: A closure which accesses the database.
|
||||
/// - throws: The error thrown by `value`, or any ``DatabaseError`` that
|
||||
/// would happen while establishing the database access.
|
||||
/// - throws: Any ``DatabaseError`` that happens while establishing the
|
||||
/// database access, or the error thrown by `value`, or
|
||||
/// `CancellationError` if the task is cancelled.
|
||||
@available(iOS 13, macOS 10.15, tvOS 13, *)
|
||||
func unsafeRead<T>(
|
||||
_ value: sending @escaping (Database) throws -> sending T
|
||||
|
||||
@@ -128,7 +128,9 @@ public protocol DatabaseWriter: DatabaseReader {
|
||||
/// can see partial updates performed by the `updates` closure.
|
||||
///
|
||||
/// - parameter updates: A closure which accesses the database.
|
||||
/// - throws: The error thrown by `updates`.
|
||||
/// - throws: Any ``DatabaseError`` that happens while establishing the
|
||||
/// database access, or the error thrown by `updates`, or
|
||||
/// `CancellationError` if the task is cancelled.
|
||||
@available(iOS 13, macOS 10.15, tvOS 13, *)
|
||||
func writeWithoutTransaction<T>(
|
||||
_ updates: sending @escaping (Database) throws -> sending T
|
||||
@@ -212,7 +214,9 @@ public protocol DatabaseWriter: DatabaseReader {
|
||||
/// can see partial updates performed by the `updates` closure.
|
||||
///
|
||||
/// - parameter updates: A closure which accesses the database.
|
||||
/// - throws: The error thrown by `updates`.
|
||||
/// - throws: Any ``DatabaseError`` that happens while establishing the
|
||||
/// database access, or the error thrown by `updates`, or
|
||||
/// `CancellationError` if the task is cancelled.
|
||||
@available(iOS 13, macOS 10.15, tvOS 13, *)
|
||||
func barrierWriteWithoutTransaction<T>(
|
||||
_ updates: sending @escaping (Database) throws -> sending T
|
||||
@@ -643,9 +647,9 @@ extension DatabaseWriter {
|
||||
/// for later use.
|
||||
///
|
||||
/// - parameter updates: A closure which accesses the database.
|
||||
/// - throws: The error thrown by `updates`, or any ``DatabaseError`` that
|
||||
/// would happen while establishing the database access or committing
|
||||
/// the transaction.
|
||||
/// - throws: Any ``DatabaseError`` that happens while establishing the
|
||||
/// database access or committing the transaction, or the error thrown
|
||||
/// by `updates`, or `CancellationError` if the task is cancelled.
|
||||
@available(iOS 13, macOS 10.15, tvOS 13, *)
|
||||
public func write<T>(
|
||||
_ updates: sending @escaping (Database) throws -> sending T
|
||||
|
||||
@@ -103,6 +103,8 @@ try dbQueue.write { db in
|
||||
|
||||
Note the identical method names: `read`, `write`. The async version is only available in async Swift functions.
|
||||
|
||||
The `async` database access methods honor task cancellation. Once the task is cancelled, reads and writes throw `CancellationError`, and any current transaction is rollbacked.
|
||||
|
||||
- **Combine publishers**
|
||||
|
||||
For example:
|
||||
|
||||
@@ -142,16 +142,21 @@ try dbQueue.writeWithoutTransaction { db
|
||||
}
|
||||
```
|
||||
|
||||
Transactions can't be left opened unless the ``Configuration/allowsUnsafeTransactions`` configuration flag is set:
|
||||
When performing manual transaction management, take care that a transaction can not be left opened at the end of a database access:
|
||||
|
||||
```swift
|
||||
// fatal error: A transaction has been left opened at the end of a database access
|
||||
// fatal error: A transaction has been left
|
||||
// opened at the end of a database access.
|
||||
try dbQueue.writeWithoutTransaction { db in
|
||||
try db.execute(sql: "BEGIN TRANSACTION")
|
||||
// <- no commit or rollback
|
||||
}
|
||||
```
|
||||
|
||||
Generally speaking, make sure you perform a rollback when a commit throws an error. The `async` database access methods honor task cancellation: in a cancelled task, all commits throw `CancellationError`, but rollbacks do not.
|
||||
|
||||
Applications that need to perform several database accesses in a long-lived transaction can use the ``Configuration/allowsUnsafeTransactions`` configuration flag.
|
||||
|
||||
It is possible to ask if a transaction is currently opened:
|
||||
|
||||
```swift
|
||||
|
||||
Reference in new issue
Block a user