Document that async methods can throw CancellationError

This commit is contained in:
Gwendal Roué committed 2024-07-28 13:59:38 +02:00
1 parent 5fad4fe028
commit 8df18fb82b
4 files changed
+24 -11

No files matched your search

+6 -4
View File
@@ -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
+9 -5
View File
@@ -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
+2
View File
@@ -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:
+7 -2
View File
@@ -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