Structure_Concurrency5.9.0
ThrowingTaskGroup
A group that contains throwing, dynamically created child tasks.
- iOS
- 13.0+
- macOS
- 10.15+
- tvOS
- 13.0+
- watchOS
- 6.0+
@frozen struct ThrowingTaskGroup<ChildTaskResult, Failure> where ChildTaskResult : Sendable, Failure : ErrorTo create a throwing task group, call the withThrowingTaskGroup(of:returning:body:) method.
Don’t use a task group from outside the task where you created it. In most cases, the Swift type system prevents a task group from escaping like that because adding a child task to a task group is a mutating operation, 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.
Cancellation behavior
A task group becomes cancelled in one of the following ways:
when
cancelAllis invoked on it,when an error is thrown out of the
withThrowingTaskGroup(...) { }closure,when the
Taskrunning this task group is cancelled.
Since a ThrowingTaskGroup 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:) rather than the plain addTask(priority:body:) which adds tasks unconditionally.
For information about the language-level concurrency model that ThrowingTaskGroup is part of, see Concurrency in The Swift Programming Language.
Citizens in _Concurrency
Members
var isCancelled: BoolA Boolean value that indicates whether the group was canceled.
var isEmpty: BoolA Boolean value that indicates whether the group has any remaining tasks.
func addTask(priority: TaskPriority?, operation: () async throws -> ChildTaskResult) Adds a child task to the group.
func addTaskUnlessCancelled(priority: TaskPriority?, operation: () async throws -> ChildTaskResult) -> Bool Adds a child task to the group, unless the group has been canceled.
func cancelAll() Cancel all of the remaining tasks in the group.
func next() async throws -> ChildTaskResult? Wait for the next child task to complete, and return the value it returned or rethrow the error it threw.
func nextResult() async -> Result<ChildTaskResult, Failure>? Wait for the next child task to complete, and return a result containing either the value that the child task returned or the error that it threw.
func waitForAll() async throws Wait for all of the group’s remaining tasks to complete.
Citizens in _Concurrency
where ChildTaskResult:Sendable, Failure:ErrorConformances
protocol AsyncSequenceA type that provides asynchronous, sequential, iterated access to its elements.
Members
func makeAsyncIterator() -> ThrowingTaskGroup<ChildTaskResult, Failure>.Iterator struct IteratorA type that provides an iteration interface over the results of tasks added to the group.
typealias AsyncIteratortypealias Elementfunc add(priority: TaskPriority?, operation: () async throws -> ChildTaskResult) async -> Bool func async(priority: TaskPriority?, operation: () async throws -> ChildTaskResult) func asyncUnlessCancelled(priority: TaskPriority?, operation: () async throws -> ChildTaskResult) -> Bool func spawn(priority: TaskPriority?, operation: () async throws -> ChildTaskResult) func spawnUnlessCancelled(priority: TaskPriority?, operation: () async throws -> ChildTaskResult) -> Bool
Features
func allSatisfy((Self.Element) async throws -> Bool) async rethrows -> Bool Returns a Boolean value that indicates whether all elements produced by the asynchronous sequence satisfy the given predicate.
func compactMap<ElementOfResult>((Self.Element) async -> ElementOfResult?) -> AsyncCompactMapSequence<Self, ElementOfResult> Creates an asynchronous sequence that maps the given closure over the asynchronous sequence’s elements, omitting results that don’t return a value.
func compactMap<ElementOfResult>((Self.Element) async throws -> ElementOfResult?) -> AsyncThrowingCompactMapSequence<Self, ElementOfResult> Creates an asynchronous sequence that maps an error-throwing closure over the base sequence’s elements, omitting results that don’t return a value.
func contains(Self.Element) async rethrows -> Bool Returns a Boolean value that indicates whether the asynchronous sequence contains the given element.
func contains(where: (Self.Element) async throws -> Bool) async rethrows -> Bool Returns a Boolean value that indicates whether the asynchronous sequence contains an element that satisfies the given predicate.
func drop(while: (Self.Element) async -> Bool) -> AsyncDropWhileSequence<Self> Omits elements from the base asynchronous sequence until a given closure returns false, after which it passes through all remaining elements.
func dropFirst(Int) -> AsyncDropFirstSequence<Self> Omits a specified number of elements from the base asynchronous sequence, then passes through all remaining elements.
func filter((Self.Element) async -> Bool) -> AsyncFilterSequence<Self> Creates an asynchronous sequence that contains, in order, the elements of the base sequence that satisfy the given predicate.
func first(where: (Self.Element) async throws -> Bool) async rethrows -> Self.Element? Returns the first element of the sequence that satisfies the given predicate.
func flatMap<SegmentOfResult>((Self.Element) async throws -> SegmentOfResult) -> AsyncThrowingFlatMapSequence<Self, SegmentOfResult> Creates an asynchronous sequence that concatenates the results of calling the given error-throwing transformation with each element of this sequence.
func flatMap<SegmentOfResult>((Self.Element) async -> SegmentOfResult) -> AsyncFlatMapSequence<Self, SegmentOfResult> Creates an asynchronous sequence that concatenates the results of calling the given transformation with each element of this sequence.
func map<Transformed>((Self.Element) async -> Transformed) -> AsyncMapSequence<Self, Transformed> Creates an asynchronous sequence that maps the given closure over the asynchronous sequence’s elements.
func map<Transformed>((Self.Element) async throws -> Transformed) -> AsyncThrowingMapSequence<Self, Transformed> Creates an asynchronous sequence that maps the given error-throwing closure over the asynchronous sequence’s elements.
func max() async rethrows -> Self.Element? Returns the maximum element in an asynchronous sequence of comparable elements.
func max(by: (Self.Element, Self.Element) async throws -> Bool) async rethrows -> Self.Element? Returns the maximum element in the asynchronous sequence, using the given predicate as the comparison between elements.
func min() async rethrows -> Self.Element? Returns the minimum element in an asynchronous sequence of comparable elements.
func min(by: (Self.Element, Self.Element) async throws -> Bool) async rethrows -> Self.Element? Returns the minimum element in the asynchronous sequence, using the given predicate as the comparison between elements.
func prefix(Int) -> AsyncPrefixSequence<Self> Returns an asynchronous sequence, up to the specified maximum length, containing the initial elements of the base asynchronous sequence.
func prefix(while: (Self.Element) async -> Bool) rethrows -> AsyncPrefixWhileSequence<Self> Returns an asynchronous sequence, containing the initial, consecutive elements of the base sequence that satisfy the given predicate.
func reduce<Result>(Result, (Result, Self.Element) async throws -> Result) async rethrows -> Result Returns the result of combining the elements of the asynchronous sequence using the given closure.
func reduce<Result>(into: Result, (inout Result, Self.Element) async throws -> Void) async rethrows -> Result Returns the result of combining the elements of the asynchronous sequence using the given closure, given a mutable initial value.