Struct Task 

pub struct Task<T>(/* private fields */);

A handle to a future that runs in the background, and to its output.

Executors return a Task from their spawn methods. gpui::Task is this type. The handle controls the future’s lifetime in three ways:

• Dropping the task cancels the future. It stops at its current .await point and is never polled again. Work it already finished stays finished. Keep the handle alive while you need the result.
• Task::detach gives up the handle and lets the future run to completion. Its output is discarded, so use this for side effects.
• Awaiting the task waits for the output. A Task implements Future, and awaiting it consumes it. If the future panics, the panic resumes in the awaiting code.

Use Task::ready for a value you already have. Use Task::fallible when a cancelled task should resolve to None instead of panicking.

Panics

Awaiting a task panics if the task closed without producing an output. This happens when the scheduler drops the runnable before it runs, as during shutdown. Use Task::fallible to get None in that case.

For the bigger picture, see gpui::_documentation::concepts::executors.

Implementations

impl<T> Task<T>

pub fn ready(val: T) -> Task<T>

Returns a task that is already complete and resolves to val.

Use it where a function returns a Task but the value is known now, such as a cache hit. No work is scheduled. Dropping or detaching the task has no effect.

Examples

let task = Task::ready(42);
assert!(task.is_ready());

pub fn from_async_task(task: Task<T, RunnableMeta>) -> Task<T>

Wraps an async_task::Task that carries RunnableMeta as its metadata.

The executors use this internally. Call it only when you build the async_task runnable yourself.

pub fn is_ready(&self) -> bool

Returns true if the output is ready to take without waiting.

A Task::ready task is always ready. A spawned task becomes ready when its future finishes, even if the output hasn’t been awaited yet. This is a snapshot: a task on another thread may finish right after the call returns false.

Examples

assert!(Task::ready("done").is_ready());

pub fn detach(self)

Lets the future run to completion in the background and discards its output.

Use this for work whose result you don’t need, such as saving a file or sending a message. Dropping the task would cancel it instead. Detaching a Task::ready task does nothing.

pub fn fallible(self) -> FallibleTask<T>

Converts this task into a FallibleTask, which resolves to None instead of panicking when the task closes without an output.

A panic inside the future still propagates to the awaiter.

impl Task<Box<dyn Any + Send + Sync>>

pub fn downcast<T>(self) -> Task<T>

where T: Send + Sync + 'static,

Converts a task that yields a boxed Any into a task that yields T.

LocalExecutor::spawn_dedicated and BackgroundExecutor::spawn_dedicated use this to recover the closure’s output type from the type-erased Scheduler::spawn_dedicated.

Panics

Polling the returned task panics if the boxed value is not a T. The check runs on poll, not in this call. A mismatch is a bug in whatever produced the inner task, because the caller chose T.

Trait Implementations

impl<T> Debug for Task<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Future for Task<T>

where T: 'static,

type Output = T

The type of value produced on completion.

fn poll( self: Pin<&mut Task<T>>, cx: &mut Context<'_>, ) -> Poll<<Task<T> as Future>::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.

impl<T, E> TaskExt<T, E> for Task<Result<T, E>>

where T: 'static, E: 'static + Display + Debug,

fn detach_and_log_err(self, cx: &App)

Runs the task to completion in the background. If it fails, the error is written to the log.

fn detach_and_log_err_with_backtrace(self, cx: &App)

Like TaskExt::detach_and_log_err, but logs the error with Debug formatting, so an anyhow::Error includes its backtrace. Use it when you need the backtrace, and the other method otherwise.