@@ -15,18 +15,18 @@ import Swift
15
15
16
16
// ==== Task Cancellation ------------------------------------------------------
17
17
18
- /// Execute an operation with cancellation handler which will immediately be
19
- /// invoked if the current task is cancelled .
18
+ /// Execute an operation with a cancellation handler that's immediately
19
+ /// invoked if the current task is canceled .
20
20
///
21
21
/// This differs from the operation cooperatively checking for cancellation
22
22
/// and reacting to it in that the cancellation handler is _always_ and
23
- /// _immediately_ invoked when the task is cancelled . For example, even if the
24
- /// operation is running code which never checks for cancellation, a cancellation
25
- /// handler still would run and give us a chance to run some cleanup code.
23
+ /// _immediately_ invoked when the task is canceled . For example, even if the
24
+ /// operation is running code that never checks for cancellation, a cancellation
25
+ /// handler still runs and provides a chance to run some cleanup code.
26
26
///
27
- /// Does not check for cancellation, and always executes the passed `operation`.
27
+ /// Doesn't check for cancellation, and always executes the passed `operation`.
28
28
///
29
- /// This function returns instantly and will never suspend .
29
+ /// This function returns immediately and never suspends .
30
30
@available ( SwiftStdlib 5 . 5 , * )
31
31
public func withTaskCancellationHandler< T> (
32
32
handler: @Sendable ( ) -> ( ) ,
@@ -49,10 +49,10 @@ public func withTaskCancellationHandler<T>(
49
49
@available ( SwiftStdlib 5 . 5 , * )
50
50
extension Task {
51
51
52
- /// Returns `true` if the task is cancelled, and should stop executing.
52
+ /// A Boolean value that indicates whether
53
+ /// the current task should stop executing.
53
54
///
54
- /// If no current `Task` is available, returns `false`, as outside of a task
55
- /// context no task cancellation may be observed.
55
+ /// If there is no current task, the value of this property is `false`.
56
56
///
57
57
/// - SeeAlso: `checkCancellation()`
58
58
public static var isCancelled : Bool {
@@ -61,26 +61,17 @@ extension Task {
61
61
}
62
62
}
63
63
64
- /// Returns `true` if the task is cancelled, and should stop executing.
64
+ /// A Boolean value that indicates whether the task should stop executing.
65
65
///
66
66
/// - SeeAlso: `checkCancellation()`
67
67
@available ( * , deprecated, message: " Storing `Task` instances has been deprecated and will be removed soon. Use the static 'Task.isCancelled' instead. " )
68
68
public var isCancelled : Bool {
69
69
_taskIsCancelled ( _task)
70
70
}
71
71
72
- /// Check if the task is cancelled and throw an `CancellationError` if it was.
72
+ /// Throws a cancellation error if the current task was canceled .
73
73
///
74
- /// It is intentional that no information is passed to the task about why it
75
- /// was cancelled. A task may be cancelled for many reasons, and additional
76
- /// reasons may accrue / after the initial cancellation (for example, if the
77
- /// task fails to immediately exit, it may pass a deadline).
78
- ///
79
- /// The goal of cancellation is to allow tasks to be cancelled in a
80
- /// lightweight way, not to be a secondary method of inter-task communication.
81
- ///
82
- /// ### Suspension
83
- /// This function returns instantly and will never suspend.
74
+ /// The error is always an instance of `Task.CancellationError`.
84
75
///
85
76
/// - SeeAlso: `isCancelled()`
86
77
public static func checkCancellation( ) throws {
@@ -97,10 +88,12 @@ extension Task {
97
88
try await withTaskCancellationHandler ( handler: handler, operation: operation)
98
89
}
99
90
100
- /// The default cancellation thrown when a task is cancelled .
91
+ /// The default error thrown by a canceled task .
101
92
///
102
- /// This error is also thrown automatically by `Task.checkCancellation()`,
103
- /// if the current task has been cancelled.
93
+ /// The `Task.checkCancellation()` method throws this error
94
+ /// if the current task has been canceled.
95
+ /// You can throw this error in your cancellation-checking code,
96
+ /// or another more specific error if needed.
104
97
public struct CancellationError : Error {
105
98
// no extra information, cancellation is intended to be light-weight
106
99
public init ( ) { }
0 commit comments