Struct smol::Task

#[must_use =
  "tasks get canceled when dropped, use `.detach()` to run them in the background"]pub struct Task<T>(_);

A spawned future.

Tasks are also futures themselves and yield the output of the spawned future.

When a task is dropped, its gets canceled and won't be polled again. To cancel a task a bit more gracefully and wait until it stops running, use the cancel() method.

Tasks that panic get immediately canceled. Awaiting a canceled task also causes a panic.

If the future panics, the panic will be unwound into the run() invocation that polled it. However, this does not apply to the blocking executor - it will simply ignore panics and continue running.

Examples

use smol::Task;

// Spawn a task onto the work-stealing executor.
let task = Task::spawn(async {
    println!("Hello from a task!");
    1 + 2
});

// Wait for the task to complete.
assert_eq!(task.await, 3);

Implementations

impl<T: 'static> Task<T>

pub fn local(future: impl Future<Output = T> + 'static) -> Task<T>

Spawns a future onto the thread-local executor.

Panics if the current thread is not inside an invocation of run().

Examples

use smol::Task;

let task = Task::local(async { 1 + 2 });
assert_eq!(task.await, 3);

impl<T: Send + 'static> Task<T>

pub fn spawn(future: impl Future<Output = T> + Send + 'static) -> Task<T>

Spawns a future onto the work-stealing executor.

This future may be stolen and polled by any thread calling run().

Examples

use smol::Task;

let task = Task::spawn(async { 1 + 2 });
assert_eq!(task.await, 3);

pub fn blocking(future: impl Future<Output = T> + Send + 'static) -> Task<T>

Spawns a future onto the blocking executor.

This future is allowed to block for an indefinite length of time.

For convenience, there is also the blocking! macro that spawns a blocking tasks and immediately awaits it.

Examples

Read a line from the standard input:

use smol::Task;
use std::io::stdin;

let line = Task::blocking(async {
    let mut line = String::new();
    std::io::stdin().read_line(&mut line).unwrap();
    line
})
.await;

See also examples for blocking!, iter(), reader(), and writer().

impl<T, E> Task<Result<T, E>> where
    T: Send + 'static,
    E: Debug + Send + 'static, 

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

Spawns a new task that awaits and unwraps the result.

The new task will panic if the original task results in an error.

Examples

use smol::{Async, Task};
use std::net::TcpStream;

let stream = Task::spawn(async {
    Async::<TcpStream>::connect("example.com:80").await
})
.unwrap()
.await;

pub fn expect(self, msg: &str) -> Task<T>

Spawns a new task that awaits and unwraps the result.

The new task will panic with the provided message if the original task results in an error.

Examples

use smol::{Async, Task};
use std::net::TcpStream;

let stream = Task::spawn(async {
    Async::<TcpStream>::connect("example.com:80").await
})
.expect("cannot connect")
.await;

impl Task<()>

pub fn detach(self)

Detaches the task to let it keep running in the background.

Examples

use smol::{Task, Timer};
use std::time::Duration;

Task::spawn(async {
    loop {
        println!("I'm a daemon task looping forever.");
        Timer::after(Duration::from_secs(1)).await;
    }
})
.detach();

impl<T> Task<T>

pub async fn cancel(self) -> Option<T>

Cancels the task and waits for it to stop running.

Returns the task's output if it was completed just before it got canceled, or None if it didn't complete.

While it's possible to simply drop the Task to cancel it, this is a cleaner way of canceling because it also waits for the task to stop running.

Examples

use smol::{Task, Timer};
use std::time::Duration;

let task = Task::spawn(async {
    loop {
        println!("Even though I'm in an infinite loop, you can still cancel me!");
        Timer::after(Duration::from_secs(1)).await;
    }
});

Timer::after(Duration::from_secs(3)).await;
task.cancel().await;

Trait Implementations

impl<T: Debug> Debug for Task<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T> Drop for Task<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Future for Task<T>

type Output = T

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output>

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

impl<T> Into<JoinHandle<T, ()>> for Task<T>

fn into(self) -> JoinHandle<T, ()>

Performs the conversion.