<!--
{
  "availability" : [
    "iOS: 13.0.0 -",
    "iPadOS: 13.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.15.0 -",
    "tvOS: 13.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 6.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Swift",
  "identifier" : "/documentation/Swift/Task",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Swift"
    ],
    "preciseIdentifier" : "s:ScT"
  },
  "title" : "Task"
}
-->

# Task

A unit of asynchronous work.

```
@frozen struct Task<Success, Failure> where Success : Sendable, Failure : Error
```

## Overview

When you create an instance of `Task`,
you provide a closure that contains the work for that task to perform.
Tasks can start running immediately after creation;
you don’t explicitly start or schedule them.
After creating a task, you use the instance to interact with it —
for example, to wait for it to complete or to cancel it.
It’s not a programming error to discard a reference to a task
without waiting for that task to finish or canceling it.
A task runs regardless of whether you keep a reference to it.
However, if you discard the reference to a task,
you give up the ability
to wait for that task’s result or cancel the task.

To support operations on the current task,
which can be either a detached task or child task,
`Task` also exposes class methods like `yield()`.
Because these methods are asynchronous,
they’re always invoked as part of an existing task.

Only code that’s running as part of the task can interact with that task.
To interact with the current task,
you call one of the static methods on `Task`.

A task’s execution can be seen as a series of periods where the task ran.
Each such period ends at a suspension point or the
completion of the task.
These periods of execution are represented by instances of `PartialAsyncTask`.
Unless you’re implementing a custom executor,
you don’t directly interact with partial tasks.

For information about the language-level concurrency model that `Task` is part of,
see [Concurrency](https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html) in [The Swift Programming Language](https://docs.swift.org/swift-book/).

# Task Cancellation

Tasks include a shared mechanism for indicating cancellation,
but not a shared implementation for how to handle cancellation.
Depending on the work you’re doing in the task,
the correct way to stop that work varies.
Likewise,
it’s the responsibility of the code running as part of the task
to check for cancellation whenever stopping is appropriate.
In a long-task that includes multiple pieces,
you might need to check for cancellation at several points,
and handle cancellation differently at each point.
If you only need to throw an error to stop the work,
call the `Task.checkCancellation()` function to check for cancellation.
Other responses to cancellation include
returning the work completed so far, returning an empty result, or returning `nil`.

Cancellation is a purely Boolean state;
there’s no way to include additional information
like the reason for cancellation.
This reflects the fact that a task can be canceled for many reasons,
and additional reasons can accrue during the cancellation process.

### Task closure lifetime

Tasks are initialized by passing a closure containing the code that will be executed by a given task.

After this code has run to completion, the task has completed, resulting in either
a failure or result value, this closure is eagerly released.

Retaining a task object doesn’t indefinitely retain the closure,
because any references that a task holds are released
after the task completes.
Consequently, tasks rarely need to capture weak references to values.

For example, in the following snippet of code it is not necessary to capture the actor as `weak`,
because as the task completes it’ll let go of the actor reference, breaking the
reference cycle between the Task and the actor holding it.

```
struct Work: Sendable {}

actor Worker {
    var work: Task<Void, Never>?
    var result: Work?

    deinit {
        // even though the task is still retained,
        // once it completes it no longer causes a reference cycle with the actor

        print("deinit actor")
    }

    func start() {
        work = Task {
            print("start task work")
            try? await Task.sleep(for: .seconds(3))
            self.result = Work() // we captured self
            print("completed task work")
            // but as the task completes, this reference is released
        }
        // we keep a strong reference to the task
    }
}
```

And using it like this:

```
await Worker().start()
```

Note that the actor is only retained by the start() method’s use of `self`,
and that the start method immediately returns, without waiting for the
unstructured `Task` to finish. Once the task is completed and its closure is
destroyed, the strong reference to the actor is also released allowing the
actor to deinitialize as expected.

Therefore, the above call will consistently result in the following output:

```other
start task work
completed task work
deinit actor
```

## Topics

### Creating a Task

[`init(name:priority:operation:)`](/documentation/Swift/Task/init(name:priority:operation:)-2dll5)

Runs the given nonthrowing operation asynchronously
as part of a new *unstructured* top-level task.

[`init(name:priority:operation:)`](/documentation/Swift/Task/init(name:priority:operation:)-43wmk)

Runs the given throwing operation asynchronously
as part of a new *unstructured* top-level task.

[`init(name:executorPreference:priority:operation:)`](/documentation/Swift/Task/init(name:executorPreference:priority:operation:)-59bfi)

Runs the given throwing operation asynchronously
as part of a new *unstructured* top-level task.

[`init(name:executorPreference:priority:operation:)`](/documentation/Swift/Task/init(name:executorPreference:priority:operation:)-81pay)

Runs the given nonthrowing operation asynchronously
as part of a new *unstructured* top-level task.

[`currentPriority`](/documentation/Swift/Task/currentPriority)

The current task’s priority.

[`basePriority`](/documentation/Swift/Task/basePriority)

The current task’s base priority.

[`withTaskPriorityEscalationHandler(operation:onPriorityEscalated:)`](/documentation/Swift/withTaskPriorityEscalationHandler(operation:onPriorityEscalated:))

Runs the passed `operation` while registering a task priority escalation handler.
The handler will be triggered concurrently to the current task if the current
is subject to priority escalation.

### Creating a Detached Task

[`detached(name:priority:operation:)`](/documentation/Swift/Task/detached(name:priority:operation:)-795w1)

Runs the given throwing operation asynchronously
as part of a new *unstructured* *detached* top-level task.

[`detached(name:priority:operation:)`](/documentation/Swift/Task/detached(name:priority:operation:)-9xki7)

Runs the given nonthrowing operation asynchronously
as part of a new *unstructured* *detached* top-level task.

[`detached(name:executorPreference:priority:operation:)`](/documentation/Swift/Task/detached(name:executorPreference:priority:operation:)-6r16s)

Runs the given throwing operation asynchronously
as part of a new *unstructured* *detached* top-level task.

[`detached(name:executorPreference:priority:operation:)`](/documentation/Swift/Task/detached(name:executorPreference:priority:operation:)-75ffe)

Runs the given nonthrowing operation asynchronously
as part of a new *unstructured* *detached* top-level task.

### Creating a Task that Starts Immediately

[`immediate(name:priority:executorPreference:operation:)`](/documentation/Swift/Task/immediate(name:priority:executorPreference:operation:)-88o80)

Create and immediately start running a new task in the context of the calling thread/task.

[`immediate(name:priority:executorPreference:operation:)`](/documentation/Swift/Task/immediate(name:priority:executorPreference:operation:)-9bghc)

Create and immediately start running a new task in the context of the calling thread/task.

[`immediateDetached(name:priority:executorPreference:operation:)`](/documentation/Swift/Task/immediateDetached(name:priority:executorPreference:operation:)-52ipd)

Create and immediately start running a new detached task in the context of the calling thread/task.

[`immediateDetached(name:priority:executorPreference:operation:)`](/documentation/Swift/Task/immediateDetached(name:priority:executorPreference:operation:)-7h41b)

Create and immediately start running a new detached task in the context of the calling thread/task.

### Accessing Results

[`value`](/documentation/Swift/Task/value-60t02)

The result from a throwing task, after it completes.

[`value`](/documentation/Swift/Task/value-40dtq)

The result from a nonthrowing task, after it completes.

[`result`](/documentation/Swift/Task/result)

The result or error from a throwing task, after it completes.

### Accessing the Current Task’s Name

[`name`](/documentation/Swift/Task/name-swift.type.property)

Returns the human-readable name of the current task,
if it was set during the tasks’ creation.

### Canceling Tasks

[`CancellationError`](/documentation/Swift/CancellationError)

An error that indicates a task was canceled.

[`cancel()`](/documentation/Swift/Task/cancel())

Cancels this task.

[`isCancelled`](/documentation/Swift/Task/isCancelled-swift.property)

A Boolean value that indicates whether the task should stop executing.

[`isCancelled`](/documentation/Swift/Task/isCancelled-swift.type.property)

A Boolean value that indicates whether the task should stop executing.

[`checkCancellation()`](/documentation/Swift/Task/checkCancellation())

Throws an error if the task was canceled.

[`withTaskCancellationHandler(operation:onCancel:)`](/documentation/Swift/withTaskCancellationHandler(operation:onCancel:))

Execute an operation with a cancellation handler that’s immediately
invoked if the current task is canceled.

[`withTaskCancellationHandler(operation:onCancel:isolation:)`](/documentation/Swift/withTaskCancellationHandler(operation:onCancel:isolation:))

Execute an operation with a cancellation handler that’s immediately
invoked if the current task is canceled.

### Shielding Tasks from Cancellation

[`withTaskCancellationShield(operation:)`](/documentation/Swift/withTaskCancellationShield(operation:)-2lzl8)

Enters a scope in which a task cancellation shield is active.

[`withTaskCancellationShield(operation:)`](/documentation/Swift/withTaskCancellationShield(operation:)-8zlgh)

Enters a scope in which a task cancellation shield is active.

### Suspending Execution

[`yield()`](/documentation/Swift/Task/yield())

Suspends the current task and allows other tasks to execute.

[`sleep(nanoseconds:)`](/documentation/Swift/Task/sleep(nanoseconds:))

Suspends the current task for at least the given duration
in nanoseconds.

[`sleep(for:tolerance:clock:)`](/documentation/Swift/Task/sleep(for:tolerance:clock:))

Suspends the current task for the given duration.

[`sleep(until:tolerance:clock:)`](/documentation/Swift/Task/sleep(until:tolerance:clock:))

Suspends the current task until the given deadline within a tolerance.

### Escalating Tasks

[`escalatePriority(to:)`](/documentation/Swift/Task/escalatePriority(to:))

Manually escalate the task `priority` of this task to the `newPriority`.

### Comparing Tasks

[`==(_:_:)`](/documentation/Swift/Task/==(_:_:))

Returns a Boolean value indicating whether two values are equal.

[`!=(_:_:)`](/documentation/Swift/Task/!=(_:_:))

Returns a Boolean value indicating whether two values are not equal.

[`hashValue`](/documentation/Swift/Task/hashValue)

The hash value.

[`hash(into:)`](/documentation/Swift/Task/hash(into:))

Hashes the essential components of this value by feeding them into the
given hasher.

### Deprecated

[`Group`](/documentation/Swift/Task/Group)

[`Handle`](/documentation/Swift/Task/Handle)

[`Priority`](/documentation/Swift/Task/Priority)

[`CancellationError()`](/documentation/Swift/Task/CancellationError())

[`getResult()`](/documentation/Swift/Task/getResult())

[`get()`](/documentation/Swift/Task/get()-4i2gt)

[`get()`](/documentation/Swift/Task/get()-4ohks)

[`sleep(_:)`](/documentation/Swift/Task/sleep(_:))

[`suspend()`](/documentation/Swift/Task/suspend())

[`runDetached(priority:operation:)`](/documentation/Swift/Task/runDetached(priority:operation:)-88zf5)

Deprecated, available only for source compatibility reasons.

[`runDetached(priority:operation:)`](/documentation/Swift/Task/runDetached(priority:operation:)-8s8lh)

Deprecated, available only for source compatibility reasons.

[`withCancellationHandler(handler:operation:)`](/documentation/Swift/Task/withCancellationHandler(handler:operation:))

[`withGroup(resultType:returning:body:)`](/documentation/Swift/Task/withGroup(resultType:returning:body:))

[`withTaskCancellationHandler(handler:operation:)`](/documentation/Swift/withTaskCancellationHandler(handler:operation:))

## Relationships

### Conforms To

[`Sendable`](/documentation/Swift/Sendable)

[`Equatable`](/documentation/Swift/Equatable)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`Hashable`](/documentation/Swift/Hashable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)