Skip to content

Commit 74c3dbc

Browse files
committed
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.
1 parent 51b2033 commit 74c3dbc

File tree

1 file changed

+17
-19
lines changed

1 file changed

+17
-19
lines changed

stdlib/public/Concurrency/TaskGroup.swift

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -265,29 +265,26 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup<ChildTaskResult, GroupR
265265
/// Structured Concurrency
266266
/// ======================
267267
///
268+
/// Structured concurrency is a way to organize your program, and tasks, in such a way that
269+
/// tasks don't outlive the scope in which they are created. Within a structured task hierarchy,
270+
/// no child task remains running longer than its parent task. This guarantee simplifies reasoning about resource usage,
271+
/// and is a powerful mechanism that you can use to write well-behaved concurrent programs.
272+
///
268273
/// A task group is the primary way to create structured concurrency tasks in Swift.
269-
/// Another way of creating structured tasks are `async let` declarations.
274+
/// Another way of creating structured tasks is an `async let` declaration.
270275
///
271276
/// Structured concurrency tasks are often called "child tasks" because of their relationship with their parent task.
272-
/// A child task will inherit the parent's priority, task-local values, and will be structured in the sense that its
273-
/// lifetime will never exceed the lifetime of the parent task.
274-
///
275-
/// A child task inherits the parent's priority, task-local values, and will be structured in the sense that its
277+
/// A child task inherits the parent's priority, task-local values, and is structured in the sense that its
276278
/// lifetime never exceeds the lifetime of the parent task.
277279
///
278280
/// A task group *always* waits for all child tasks to complete before it's destroyed.
279281
/// Specifically, `with...TaskGroup` APIs don't return until all the child tasks
280282
/// created in the group's scope have completed running.
281283
///
282-
/// Structured concurrency is a way to organize your program, and tasks, in such a way that
283-
/// tasks don't outlive the scope in which they are created. Within a structured task hierarchy,
284-
/// no child task will remains running longer than its parent task. This simplifies reasoning about resource usage,
285-
/// and is a powerful mechanism that you can use to write well-behaved concurrent programs.
286-
///
287-
/// Structured Concurrency APIs (including task groups and `async let`), will *always* await the
284+
/// Structured concurrency APIs (including task groups and `async let`), *always* waits for the
288285
/// completion of tasks contained within their scope before returning. Specifically, this means that
289-
/// even if one were to await a single task result and return it from a `withTaskGroup` function body,
290-
/// the group will automatically await all the remaining tasks before returning:
286+
/// even if you await a single task result and return it from a `withTaskGroup` function body,
287+
/// the group automatically waits for all the remaining tasks before returning:
291288
///
292289
/// func takeFirst(actions: [@Sendable () -> Int]) async -> Int? {
293290
/// await withTaskGroup { group in
@@ -300,7 +297,7 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup<ChildTaskResult, GroupR
300297
/// }
301298
///
302299
/// In the above example, even though the code returns the first collected integer from all actions added to the task group,
303-
/// the task group will *always*, automatically, waits for the completion of all the resulting tasks.
300+
/// the task group *always*, automatically, waits for the completion of all the resulting tasks.
304301
///
305302
/// You can use `group.cancelAll()` to signal cancellation to the remaining in-progress tasks,
306303
/// however this doesn't interrupt their execution automatically.
@@ -326,7 +323,7 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup<ChildTaskResult, GroupR
326323
/// but other tasks are better not even being created
327324
/// when you know they can't produce useful results.
328325
///
329-
/// In non-throwing task groups the tasks you add to a group with this method are nonthrowing,
326+
/// In nonthrowing task groups the tasks you add to a group with this method are nonthrowing,
330327
/// those tasks can't respond to cancellation by throwing `CancellationError`.
331328
/// The tasks must handle cancellation in some other way,
332329
/// such as returning the work completed so far, returning an empty result, or returning `nil`.
@@ -339,17 +336,18 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup<ChildTaskResult, GroupR
339336
/// any order.
340337
///
341338
/// ### Cancellation behavior
339+
///
342340
/// A task group becomes canceled in one of the following ways:
343341
///
344-
/// - when ``cancelAll()`` is invoked on it,
345-
/// - when the ``Task`` running this task group is canceled.
342+
/// - When ``cancelAll()`` is invoked on it.
343+
/// - When the ``Task`` running this task group is canceled.
346344
///
347-
/// Since a `TaskGroup` is a structured concurrency primitive, cancellation is
345+
/// Because a `TaskGroup` is a structured concurrency primitive, cancellation is
348346
/// automatically propagated through all of its child-tasks (and their child
349347
/// tasks).
350348
///
351349
/// A canceled task group can still keep adding tasks, however they will start
352-
/// being immediately canceled, and may act accordingly to this. To avoid adding
350+
/// being immediately canceled, and might respond accordingly. To avoid adding
353351
/// new tasks to an already canceled task group, use ``addTaskUnlessCancelled(name:priority:body:)``
354352
/// rather than the plain ``addTask(name:priority:body:)`` which adds tasks unconditionally.
355353
///

0 commit comments

Comments
 (0)