From 1416a74f11c25c481f770f66c79c156e42280a73 Mon Sep 17 00:00:00 2001 From: Changhyun Kang Date: Tue, 8 Jul 2025 21:02:19 +0900 Subject: [PATCH 1/5] [Concurrency] fix documentation typos in TaskGroup.swift (#82291) --- stdlib/public/Concurrency/TaskGroup.swift | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stdlib/public/Concurrency/TaskGroup.swift b/stdlib/public/Concurrency/TaskGroup.swift index 3b0e4728c5cac..fa16d8bb963ad 100644 --- a/stdlib/public/Concurrency/TaskGroup.swift +++ b/stdlib/public/Concurrency/TaskGroup.swift @@ -364,7 +364,7 @@ public struct TaskGroup { /// return collected /// /// Awaiting on an empty group - /// immediate returns `nil` without suspending. + /// immediately returns `nil` without suspending. /// /// You can also use a `for`-`await`-`in` loop to collect results of a task group: /// @@ -423,7 +423,7 @@ public struct TaskGroup { /// /// At the start of the body of a `withTaskGroup(of:returning:body:)` call, /// the task group is always empty. - /// It`s guaranteed to be empty when returning from that body + /// It's guaranteed to be empty when returning from that body /// because a task group waits for all child tasks to complete before returning. /// /// - Returns: `true` if the group has no pending tasks; otherwise `false`. From 7a6527af834f09dfff340f13f930d4031f3d2814 Mon Sep 17 00:00:00 2001 From: Konrad `ktoso` Malawski Date: Tue, 8 Jul 2025 17:06:51 +0900 Subject: [PATCH 2/5] Merge pull request #82558 from ktoso/wip-cleanup-group-docs --- .../Concurrency/DiscardingTaskGroup.swift | 51 +++--- stdlib/public/Concurrency/TaskGroup.swift | 157 ++++++++++++------ utils/swift_snapshot_tool/Package.resolved | 15 ++ 3 files changed, 143 insertions(+), 80 deletions(-) create mode 100644 utils/swift_snapshot_tool/Package.resolved diff --git a/stdlib/public/Concurrency/DiscardingTaskGroup.swift b/stdlib/public/Concurrency/DiscardingTaskGroup.swift index 0fcec55446e16..41103f9e8e2f8 100644 --- a/stdlib/public/Concurrency/DiscardingTaskGroup.swift +++ b/stdlib/public/Concurrency/DiscardingTaskGroup.swift @@ -22,8 +22,8 @@ import Swift /// best applied in situations where the result of a child task is some form /// of side-effect. /// -/// A group waits for all of its child tasks -/// to complete before it returns. Even cancelled tasks must run until +/// A group *always* waits for all of its child tasks +/// to complete before it returns. Even canceled tasks must run until /// completion before this function returns. /// Cancelled child tasks cooperatively react to cancellation and attempt /// to return as early as possible. @@ -41,6 +41,8 @@ import Swift /// // guaranteed that slow-task has completed and the group is empty & destroyed /// ``` /// +/// Refer to ``TaskGroup`` documentation for detailed discussion of semantics shared between all task groups. +/// /// Task Group Cancellation /// ======================= /// @@ -65,6 +67,7 @@ import Swift /// For tasks that need to handle cancellation by throwing an error, /// use the `withThrowingDiscardingTaskGroup(returning:body:)` method instead. /// +/// - SeeAlso: ``TaskGroup`` /// - SeeAlso: ``withThrowingDiscardingTaskGroup(returning:body:)`` @available(SwiftStdlib 5.9, *) #if !hasFeature(Embedded) @@ -131,9 +134,7 @@ public func _unsafeInheritExecutor_withDiscardingTaskGroup( /// and mutation operations can't be performed /// from a concurrent execution context like a child task. /// -/// ### Task execution order -/// Tasks added to a task group execute concurrently, and may be scheduled in -/// any order. +/// Refer to ``TaskGroup`` documentation for detailed discussion of semantics shared between all task groups. /// /// ### Discarding behavior /// A discarding task group eagerly discards and releases its child tasks as @@ -142,18 +143,18 @@ public func _unsafeInheritExecutor_withDiscardingTaskGroup( /// be the case with a ``TaskGroup``. /// /// ### Cancellation behavior -/// A discarding task group becomes cancelled in one of the following ways: +/// A discarding task group becomes canceled in one of the following ways: /// /// - when ``cancelAll()`` is invoked on it, -/// - when the ``Task`` running this task group is cancelled. +/// - when the ``Task`` running this task group is canceled. /// /// Since a `DiscardingTaskGroup` is a structured concurrency primitive, cancellation is /// automatically propagated through all of its child-tasks (and their child /// tasks). /// -/// A cancelled task group can still keep adding tasks, however they will start -/// being immediately cancelled, and may act accordingly to this. To avoid adding -/// new tasks to an already cancelled task group, use ``addTaskUnlessCancelled(priority:body:)`` +/// A canceled task group can still keep adding tasks, however they will start +/// being immediately canceled, and may act accordingly to this. To avoid adding +/// new tasks to an already canceled task group, use ``addTaskUnlessCancelled(priority:body:)`` /// rather than the plain ``addTask(priority:body:)`` which adds tasks unconditionally. /// /// For information about the language-level concurrency model that `DiscardingTaskGroup` is part of, @@ -204,7 +205,7 @@ public struct DiscardingTaskGroup { /// If you add a task to a group after canceling the group, /// that task is canceled immediately after being added to the group. /// - /// Immediately cancelled child tasks should therefore cooperatively check for and + /// Immediately canceled child tasks should therefore cooperatively check for and /// react to cancellation, e.g. by throwing an `CancellationError` at their /// earliest convenience, or otherwise handling the cancellation. /// @@ -245,10 +246,10 @@ extension DiscardingTaskGroup: Sendable { } /// best applied in situations where the result of a child task is some form /// of side-effect. /// -/// A group waits for all of its child tasks -/// to complete before it returns. Even cancelled tasks must run until +/// A group *always* waits for all of its child tasks +/// to complete before it returns. Even canceled tasks must run until /// completion before this function returns. -/// Cancelled child tasks cooperatively react to cancellation and attempt +/// Canceled child tasks cooperatively react to cancellation and attempt /// to return as early as possible. /// After this function returns, the task group is always empty. /// @@ -264,6 +265,8 @@ extension DiscardingTaskGroup: Sendable { } /// // guaranteed that slow-task has completed and the group is empty & destroyed /// ``` /// +/// Refer to ``TaskGroup`` documentation for detailed discussion of semantics shared between all task groups. +/// /// Task Group Cancellation /// ======================= /// @@ -411,9 +414,7 @@ public func _unsafeInheritExecutor_withThrowingDiscardingTaskGroup( /// and mutation operations can't be performed /// from a concurrent execution context like a child task. /// -/// ### Task execution order -/// Tasks added to a task group execute concurrently, and may be scheduled in -/// any order. +/// Refer to ``TaskGroup`` documentation for detailed discussion of semantics shared between all task groups. /// /// ### Discarding behavior /// A discarding task group eagerly discards and releases its child tasks as @@ -422,20 +423,20 @@ public func _unsafeInheritExecutor_withThrowingDiscardingTaskGroup( /// be the case with a ``TaskGroup``. /// /// ### Cancellation behavior -/// A throwing discarding task group becomes cancelled in one of the following ways: +/// A throwing discarding task group becomes canceled in one of the following ways: /// /// - when ``cancelAll()`` is invoked on it, /// - when an error is thrown out of the `withThrowingDiscardingTaskGroup { ... }` closure, -/// - when the ``Task`` running this task group is cancelled. +/// - when the ``Task`` running this task group is canceled . /// /// But also, and uniquely in *discarding* task groups: /// - when *any* of its child tasks throws. /// -/// The group becoming cancelled automatically, and cancelling all of its child tasks, +/// The group becoming canceled automatically, and cancelling all of its child tasks, /// whenever *any* child task throws an error is a behavior unique to discarding task groups, /// because achieving such semantics is not possible otherwise, due to the missing `next()` method /// on discarding groups. Accumulating task groups can implement this by manually polling `next()` -/// and deciding to `cancelAll()` when they decide an error should cause the group to become cancelled, +/// and deciding to `cancelAll()` when they decide an error should cause the group to become canceled, /// however a discarding group cannot poll child tasks for results and therefore assumes that child /// task throws are an indication of a group wide failure. In order to avoid such behavior, /// use a ``DiscardingTaskGroup`` instead of a throwing one, or catch specific errors in @@ -445,9 +446,9 @@ public func _unsafeInheritExecutor_withThrowingDiscardingTaskGroup( /// automatically propagated through all of its child-tasks (and their child /// tasks). /// -/// A cancelled task group can still keep adding tasks, however they will start -/// being immediately cancelled, and may act accordingly to this. To avoid adding -/// new tasks to an already cancelled task group, use ``addTaskUnlessCancelled(priority:body:)`` +/// A canceled task group can still keep adding tasks, however they will start +/// being immediately canceled, and may act accordingly to this. To avoid adding +/// new tasks to an already canceled task group, use ``addTaskUnlessCancelled(priority:body:)`` /// rather than the plain ``addTask(priority:body:)`` which adds tasks unconditionally. /// /// For information about the language-level concurrency model that `DiscardingTaskGroup` is part of, @@ -496,7 +497,7 @@ public struct ThrowingDiscardingTaskGroup { /// If you add a task to a group after canceling the group, /// that task is canceled immediately after being added to the group. /// - /// Immediately cancelled child tasks should therefore cooperatively check for and + /// Immediately canceled child tasks should therefore cooperatively check for and /// react to cancellation, e.g. by throwing an `CancellationError` at their /// earliest convenience, or otherwise handling the cancellation. /// diff --git a/stdlib/public/Concurrency/TaskGroup.swift b/stdlib/public/Concurrency/TaskGroup.swift index fa16d8bb963ad..c4d72f75aa12c 100644 --- a/stdlib/public/Concurrency/TaskGroup.swift +++ b/stdlib/public/Concurrency/TaskGroup.swift @@ -16,8 +16,11 @@ import Swift /// Starts a new scope that can contain a dynamic number of child tasks. /// -/// A group waits for all of its child tasks -/// to complete or be canceled before it returns. +/// A group *always* waits for all of its child tasks +/// to complete before it returns. Even cancelled tasks must run until +/// completion before this function returns. +/// Cancelled child tasks cooperatively react to cancellation and attempt +/// to return as early as possible. /// After this function returns, the task group is always empty. /// /// To collect the results of the group's child tasks, @@ -39,29 +42,9 @@ import Swift /// group.cancelAll() /// return first + second /// -/// Task Group Cancellation -/// ======================= -/// -/// You can cancel a task group and all of its child tasks -/// by calling the `cancelAll()` method on the task group, -/// or by canceling the task in which the group is running. -/// -/// If you call `addTask(name:priority:operation:)` to create a new task in a canceled group, -/// that task is immediately canceled after creation. -/// Alternatively, you can call `addTaskUnlessCancelled(name:priority:operation:)`, -/// which doesn't create the task if the group has already been canceled. -/// Choosing between these two functions -/// lets you control how to react to cancellation within a group: -/// some child tasks need to run regardless of cancellation, -/// but other tasks are better not even being created -/// when you know they can't produce useful results. +/// Refer to ``TaskGroup`` documentation for detailed discussion of semantics shared between all task groups. /// -/// Because the tasks you add to a group with this method are nonthrowing, -/// those tasks can't respond to cancellation by throwing `CancellationError`. -/// The tasks must handle cancellation in some other way, -/// such as returning the work completed so far, returning an empty result, or returning `nil`. -/// For tasks that need to handle cancellation by throwing an error, -/// use the `withThrowingTaskGroup(of:returning:body:)` method instead. +/// - SeeAlso: ``TaskGroup`` @available(SwiftStdlib 5.1, *) #if !hasFeature(Embedded) @backDeployed(before: SwiftStdlib 6.0) @@ -126,10 +109,10 @@ public func _unsafeInheritExecutor_withTaskGroup( /// Starts a new scope that can contain a dynamic number of throwing child tasks. /// -/// A group waits for all of its child tasks -/// to complete before it returns. Even cancelled tasks must run until +/// A group *always* waits for all of its child tasks +/// to complete before it returns. Even canceled tasks must run until /// completion before this function returns. -/// Cancelled child tasks cooperatively react to cancellation and attempt +/// Canceled child tasks cooperatively react to cancellation and attempt /// to return as early as possible. /// After this function returns, the task group is always empty. /// @@ -152,23 +135,6 @@ public func _unsafeInheritExecutor_withTaskGroup( /// group.cancelAll() /// return first + second /// -/// Task Group Cancellation -/// ======================= -/// -/// You can cancel a task group and all of its child tasks -/// by calling the `cancelAll()` method on the task group, -/// or by canceling the task in which the group is running. -/// -/// If you call `addTask(name:priority:operation:)` to create a new task in a canceled group, -/// that task is immediately canceled after creation. -/// Alternatively, you can call `addTaskUnlessCancelled(name:priority:operation:)`, -/// which doesn't create the task if the group has already been canceled. -/// Choosing between these two functions -/// lets you control how to react to cancellation within a group: -/// some child tasks need to run regardless of cancellation, -/// but other tasks are better not even being created -/// when you know they can't produce useful results. -/// /// Error Handling /// ============== /// @@ -199,6 +165,12 @@ public func _unsafeInheritExecutor_withTaskGroup( /// in the corresponding call to `Group.next()`, /// which gives you a chance to handle the individual error /// or to let the group rethrow the error. +/// +/// Refer to ``TaskGroup`` documentation for detailed discussion of semantics shared between all task groups. +/// +/// - SeeAlso: ``TaskGroup`` +/// - SeeAlso: ``ThrowingTaskGroup`` +/// - SeeAlso: ``ThrowingDiscardingTaskGroup`` @available(SwiftStdlib 5.1, *) #if !hasFeature(Embedded) @backDeployed(before: SwiftStdlib 6.0) @@ -290,13 +262,84 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup Int]) async -> Int? { +/// await withTaskGroup { group in +/// for action in actions { +/// group.addTask { action() } +/// } +/// +/// return await group.next() // return the first action to complete +/// } // the group will ALWAYS await the completion of all the actions (!) +/// } +/// +/// In the above example, even though the code returns the first collected integer from all actions added to the task group, +/// the task group will *always*, automatically, waits for the completion of all the resulting tasks. +/// +/// You can use `group.cancelAll()` to signal cancellation to the remaining in-progress tasks, +/// however this doesn't interrupt their execution automatically. +/// Rather, the child tasks need to cooperatively react to the cancellation, +/// and return early if that's possible. +/// +/// To create unstructured concurrency tasks, you can use ``Task.init``, ``Task.detached`` or ``Task.immediate``. +/// +/// Task Group Cancellation +/// ======================= +/// +/// You can cancel a task group and all of its child tasks +/// by calling the `cancelAll()` method on the task group, +/// or by canceling the task in which the group is running. +/// +/// If you call `addTask(name:priority:operation:)` to create a new task in a canceled group, +/// that task is immediately canceled after creation. +/// Alternatively, you can call `addTaskUnlessCancelled(name:priority:operation:)`, +/// which doesn't create the task if the group has already been canceled. +/// Choosing between these two functions +/// lets you control how to react to cancellation within a group: +/// some child tasks need to run regardless of cancellation, +/// but other tasks are better not even being created +/// when you know they can't produce useful results. +/// +/// In non-throwing task groups the tasks you add to a group with this method are nonthrowing, +/// those tasks can't respond to cancellation by throwing `CancellationError`. +/// The tasks must handle cancellation in some other way, +/// such as returning the work completed so far, returning an empty result, or returning `nil`. +/// For tasks that need to handle cancellation by throwing an error, +/// use the `withThrowingTaskGroup(of:returning:body:)` method instead. +/// /// ### Task execution order /// /// Tasks added to a task group execute concurrently, and may be scheduled in /// any order. /// /// ### Cancellation behavior -/// A task group becomes cancelled in one of the following ways: +/// A task group becomes canceled in one of the following ways: /// /// - when ``cancelAll()`` is invoked on it, /// - when the ``Task`` running this task group is cancelled. @@ -305,9 +348,9 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup { @@ -436,7 +482,7 @@ public struct TaskGroup { /// If you add a task to a group after canceling the group, /// that task is canceled immediately after being added to the group. /// - /// Immediately cancelled child tasks should therefore cooperatively check for and + /// Immediately canceled child tasks should therefore cooperatively check for and /// react to cancellation, e.g. by throwing an `CancellationError` at their /// earliest convenience, or otherwise handling the cancellation. /// @@ -498,12 +544,10 @@ extension TaskGroup: Sendable { } /// and mutation operations can't be performed /// from concurrent execution contexts like a child task. /// -/// ### Task execution order -/// Tasks added to a task group execute concurrently, and may be scheduled in -/// any order. +/// Refer to ``TaskGroup`` documentation for detailed discussion of semantics shared between all task groups. /// /// ### Cancellation behavior -/// A task group becomes cancelled in one of the following ways: +/// A task group becomes canceled in one of the following ways: /// /// - when ``cancelAll()`` is invoked on it, /// - when an error is thrown out of the `withThrowingTaskGroup(...) { }` closure, @@ -513,9 +557,9 @@ extension TaskGroup: Sendable { } /// automatically propagated through all of its child-tasks (and their child /// tasks). /// -/// A cancelled task group can still keep adding tasks, however they will start +/// A canceled task group can still keep adding tasks, however they will start /// being immediately cancelled, and may act accordingly to this. To avoid adding -/// new tasks to an already cancelled task group, use ``addTaskUnlessCancelled(priority:body:)`` +/// new tasks to an already canceled task group, use ``addTaskUnlessCancelled(priority:body:)`` /// rather than the plain ``addTask(priority:body:)`` which adds tasks unconditionally. /// /// For information about the language-level concurrency model that `ThrowingTaskGroup` is part of, @@ -524,6 +568,9 @@ extension TaskGroup: Sendable { } /// [concurrency]: https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html /// [tspl]: https://docs.swift.org/swift-book/ /// +/// - SeeAlso: ``TaskGroup`` +/// - SeeAlso: ``DiscardingTaskGroup`` +/// - SeeAlso: ``ThrowingDiscardingTaskGroup`` @available(SwiftStdlib 5.1, *) @frozen public struct ThrowingTaskGroup { @@ -761,7 +808,7 @@ public struct ThrowingTaskGroup { /// If you add a task to a group after canceling the group, /// that task is canceled immediately after being added to the group. /// - /// Immediately cancelled child tasks should therefore cooperatively check for and + /// Immediately canceled child tasks should therefore cooperatively check for and /// react to cancellation, e.g. by throwing an `CancellationError` at their /// earliest convenience, or otherwise handling the cancellation. /// diff --git a/utils/swift_snapshot_tool/Package.resolved b/utils/swift_snapshot_tool/Package.resolved new file mode 100644 index 0000000000000..3dcc511149ffb --- /dev/null +++ b/utils/swift_snapshot_tool/Package.resolved @@ -0,0 +1,15 @@ +{ + "originHash" : "80ba966d30db4d84324c2bda4f2b419b9e6fe208fa1f70080f74c7aa3d432a49", + "pins" : [ + { + "identity" : "swift-argument-parser", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-argument-parser", + "state" : { + "revision" : "41982a3656a71c768319979febd796c6fd111d5c", + "version" : "1.5.0" + } + } + ], + "version" : 3 +} From 929a167edaa003ea746518df5e4b408019fcce46 Mon Sep 17 00:00:00 2001 From: Alex Martini Date: Tue, 8 Jul 2025 10:45:36 -0700 Subject: [PATCH 3/5] Remove stray spaces These looks like the side effect of a find-and-replace for PR 82558 fixing 'cancelled' vs 'canceled'. --- stdlib/public/Concurrency/DiscardingTaskGroup.swift | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/stdlib/public/Concurrency/DiscardingTaskGroup.swift b/stdlib/public/Concurrency/DiscardingTaskGroup.swift index 41103f9e8e2f8..563e5376ee11f 100644 --- a/stdlib/public/Concurrency/DiscardingTaskGroup.swift +++ b/stdlib/public/Concurrency/DiscardingTaskGroup.swift @@ -205,7 +205,7 @@ public struct DiscardingTaskGroup { /// If you add a task to a group after canceling the group, /// that task is canceled immediately after being added to the group. /// - /// Immediately canceled child tasks should therefore cooperatively check for and + /// Immediately canceled child tasks should therefore cooperatively check for and /// react to cancellation, e.g. by throwing an `CancellationError` at their /// earliest convenience, or otherwise handling the cancellation. /// @@ -427,7 +427,7 @@ public func _unsafeInheritExecutor_withThrowingDiscardingTaskGroup( /// /// - when ``cancelAll()`` is invoked on it, /// - when an error is thrown out of the `withThrowingDiscardingTaskGroup { ... }` closure, -/// - when the ``Task`` running this task group is canceled . +/// - when the ``Task`` running this task group is canceled. /// /// But also, and uniquely in *discarding* task groups: /// - when *any* of its child tasks throws. @@ -436,7 +436,7 @@ public func _unsafeInheritExecutor_withThrowingDiscardingTaskGroup( /// whenever *any* child task throws an error is a behavior unique to discarding task groups, /// because achieving such semantics is not possible otherwise, due to the missing `next()` method /// on discarding groups. Accumulating task groups can implement this by manually polling `next()` -/// and deciding to `cancelAll()` when they decide an error should cause the group to become canceled, +/// and deciding to `cancelAll()` when they decide an error should cause the group to become canceled, /// however a discarding group cannot poll child tasks for results and therefore assumes that child /// task throws are an indication of a group wide failure. In order to avoid such behavior, /// use a ``DiscardingTaskGroup`` instead of a throwing one, or catch specific errors in @@ -447,7 +447,7 @@ public func _unsafeInheritExecutor_withThrowingDiscardingTaskGroup( /// tasks). /// /// A canceled task group can still keep adding tasks, however they will start -/// being immediately canceled, and may act accordingly to this. To avoid adding +/// being immediately canceled, and may act accordingly to this. To avoid adding /// new tasks to an already canceled task group, use ``addTaskUnlessCancelled(priority:body:)`` /// rather than the plain ``addTask(priority:body:)`` which adds tasks unconditionally. /// From 430f49b98bbb57c0001a97ead8d93b578c9f1bad Mon Sep 17 00:00:00 2001 From: Alex Martini Date: Tue, 8 Jul 2025 10:50:43 -0700 Subject: [PATCH 4/5] Fix more 'cancel(l)ed' style issues --- .../public/Concurrency/DiscardingTaskGroup.swift | 2 +- stdlib/public/Concurrency/TaskCancellation.swift | 6 +++--- stdlib/public/Concurrency/TaskGroup.swift | 14 +++++++------- stdlib/public/Concurrency/TaskSleepDuration.swift | 2 +- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/stdlib/public/Concurrency/DiscardingTaskGroup.swift b/stdlib/public/Concurrency/DiscardingTaskGroup.swift index 563e5376ee11f..bfb8246da2d86 100644 --- a/stdlib/public/Concurrency/DiscardingTaskGroup.swift +++ b/stdlib/public/Concurrency/DiscardingTaskGroup.swift @@ -25,7 +25,7 @@ import Swift /// A group *always* waits for all of its child tasks /// to complete before it returns. Even canceled tasks must run until /// completion before this function returns. -/// Cancelled child tasks cooperatively react to cancellation and attempt +/// Canceled child tasks cooperatively react to cancellation and attempt /// to return as early as possible. /// After this function returns, the task group is always empty. /// diff --git a/stdlib/public/Concurrency/TaskCancellation.swift b/stdlib/public/Concurrency/TaskCancellation.swift index cd0a2bfaf5fb7..90c85c02790dc 100644 --- a/stdlib/public/Concurrency/TaskCancellation.swift +++ b/stdlib/public/Concurrency/TaskCancellation.swift @@ -39,13 +39,13 @@ import Swift /// ### Execution order and semantics /// The `operation` closure is always invoked, even when the /// `withTaskCancellationHandler(operation:onCancel:)` method is called from a task -/// that was already cancelled. +/// that was already canceled. /// /// When `withTaskCancellationHandler(operation:onCancel:)` is used in a task that has already been -/// cancelled, the cancellation handler will be executed +/// canceled, the cancellation handler will be executed /// immediately before the `operation` closure gets to execute. /// -/// This allows the cancellation handler to set some external "cancelled" flag +/// This allows the cancellation handler to set some external "canceled" flag /// that the operation may be *atomically* checking for in order to avoid /// performing any actual work once the operation gets to run. /// diff --git a/stdlib/public/Concurrency/TaskGroup.swift b/stdlib/public/Concurrency/TaskGroup.swift index c4d72f75aa12c..31724abe339f2 100644 --- a/stdlib/public/Concurrency/TaskGroup.swift +++ b/stdlib/public/Concurrency/TaskGroup.swift @@ -17,9 +17,9 @@ import Swift /// Starts a new scope that can contain a dynamic number of child tasks. /// /// A group *always* waits for all of its child tasks -/// to complete before it returns. Even cancelled tasks must run until +/// to complete before it returns. Even canceled tasks must run until /// completion before this function returns. -/// Cancelled child tasks cooperatively react to cancellation and attempt +/// Canceled child tasks cooperatively react to cancellation and attempt /// to return as early as possible. /// After this function returns, the task group is always empty. /// @@ -342,14 +342,14 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup { /// Wait for all of the group's remaining tasks to complete. /// /// If any of the tasks throw, the *first* error thrown is captured - /// and re-thrown by this method although the task group is *not* cancelled + /// and re-thrown by this method although the task group is *not* canceled /// when this happens. /// /// ### Cancelling the task group on first error diff --git a/stdlib/public/Concurrency/TaskSleepDuration.swift b/stdlib/public/Concurrency/TaskSleepDuration.swift index d9e3876c69534..6b4c3b894c882 100644 --- a/stdlib/public/Concurrency/TaskSleepDuration.swift +++ b/stdlib/public/Concurrency/TaskSleepDuration.swift @@ -209,7 +209,7 @@ extension Task where Success == Never, Failure == Never { /// Suspends the current task for the given duration. /// - /// If the task is cancelled before the time ends, this function throws + /// If the task is canceled before the time ends, this function throws /// `CancellationError`. /// /// This function doesn't block the underlying thread. From 12b998e4bc340b60cf12ed3059bf693fc7de0647 Mon Sep 17 00:00:00 2001 From: Alex Martini Date: Tue, 8 Jul 2025 13:59:11 -0700 Subject: [PATCH 5/5] Revise doc comment for style & clarity - Move the definition of 'structured concurrency' to the beginning of the section. - Avoid future tense. Fix some mixed future+present tense errors. - Write bullet points as individual sentences, not as the clauses of one long sentence. - Apple Style: Use 'since' only in the sense of 'after'. - Apple Style: Use 'you' instead of 'one'. - Apple Style: Close up 'non-' except when ambiguous. - DevPubs style: Avoid bare 'this' for clarity. Here, 'this guarantee' tells the reader what 'this' refers to. - DevPubs style: Avoid 'may' which can be ambiguous between possibility and permission. --- stdlib/public/Concurrency/TaskGroup.swift | 36 ++++++++++------------ utils/swift_snapshot_tool/Package.resolved | 15 --------- 2 files changed, 17 insertions(+), 34 deletions(-) delete mode 100644 utils/swift_snapshot_tool/Package.resolved diff --git a/stdlib/public/Concurrency/TaskGroup.swift b/stdlib/public/Concurrency/TaskGroup.swift index 31724abe339f2..501404094c993 100644 --- a/stdlib/public/Concurrency/TaskGroup.swift +++ b/stdlib/public/Concurrency/TaskGroup.swift @@ -265,29 +265,26 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup Int]) async -> Int? { /// await withTaskGroup { group in @@ -300,7 +297,7 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup