pub struct Task<T> { /* private fields */ }
Expand description
A spawned task.
A Task
can be awaited to retrieve the output of its future.
Dropping a Task
cancels it, which means its future won’t be polled again. To drop the
Task
handle without canceling it, use detach()
instead. To cancel a
task gracefully and wait until it is fully destroyed, use the cancel()
method.
Note that canceling a task actually wakes it and reschedules one last time. Then, the executor
can destroy the task by simply dropping its Runnable
or by invoking
run()
.
Examples
use smol::{future, Executor};
use std::thread;
let ex = Executor::new();
// Spawn a future onto the executor.
let task = ex.spawn(async {
println!("Hello from a task!");
1 + 2
});
// Run an executor thread.
thread::spawn(move || future::block_on(ex.run(future::pending::<()>())));
// Wait for the task's output.
assert_eq!(future::block_on(task), 3);
Implementations
sourceimpl<T> Task<T>
impl<T> Task<T>
sourcepub fn detach(self)
pub fn detach(self)
Detaches the task to let it keep running in the background.
Examples
use smol::{Executor, Timer};
use std::time::Duration;
let ex = Executor::new();
// Spawn a deamon future.
ex.spawn(async {
loop {
println!("I'm a daemon task looping forever.");
Timer::after(Duration::from_secs(1)).await;
}
})
.detach();
sourcepub async fn cancel(self) -> Option<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::{future, Executor, Timer};
use std::thread;
use std::time::Duration;
let ex = Executor::new();
// Spawn a deamon future.
let task = ex.spawn(async {
loop {
println!("Even though I'm in an infinite loop, you can still cancel me!");
Timer::after(Duration::from_secs(1)).await;
}
});
// Run an executor thread.
thread::spawn(move || future::block_on(ex.run(future::pending::<()>())));
future::block_on(async {
Timer::after(Duration::from_secs(3)).await;
task.cancel().await;
});
sourcepub fn fallible(self) -> FallibleTask<T>ⓘNotable traits for FallibleTask<T>impl<T> Future for FallibleTask<T> type Output = Option<T>;
pub fn fallible(self) -> FallibleTask<T>ⓘNotable traits for FallibleTask<T>impl<T> Future for FallibleTask<T> type Output = Option<T>;
Converts this task into a FallibleTask
.
Like Task
, a fallible task will poll the task’s output until it is
completed or cancelled due to its Runnable
being
dropped without being run. Resolves to the task’s output when completed,
or None
if it didn’t complete.
Examples
use smol::{future, Executor};
use std::thread;
let ex = Executor::new();
// Spawn a future onto the executor.
let task = ex.spawn(async {
println!("Hello from a task!");
1 + 2
})
.fallible();
// Run an executor thread.
thread::spawn(move || future::block_on(ex.run(future::pending::<()>())));
// Wait for the task's output.
assert_eq!(future::block_on(task), Some(3));
use smol::future;
// Schedule function which drops the runnable without running it.
let schedule = move |runnable| drop(runnable);
// Create a task with the future and the schedule function.
let (runnable, task) = async_task::spawn(async {
println!("Hello from a task!");
1 + 2
}, schedule);
runnable.schedule();
// Wait for the task's output.
assert_eq!(future::block_on(task.fallible()), None);
sourcepub fn is_finished(&self) -> bool
pub fn is_finished(&self) -> bool
Returns true
if the current task is finished.
Note that in a multithreaded environment, this task can change finish immediately after calling this function.
Trait Implementations
impl<T> RefUnwindSafe for Task<T>
impl<T> Send for Task<T> where
T: Send,
impl<T> Sync for Task<T>
impl<T> Unpin for Task<T>
impl<T> UnwindSafe for Task<T>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<F> FutureExt for F where
F: Future + ?Sized,
impl<F> FutureExt for F where
F: Future + ?Sized,
sourcefn poll(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output> where
Self: Unpin,
fn poll(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output> where
Self: Unpin,
A convenience for calling Future::poll()
on !
Unpin
types.
sourcefn or<F>(self, other: F) -> Or<Self, F>ⓘNotable traits for Or<F1, F2>impl<T, F1, F2> Future for Or<F1, F2> where
F1: Future<Output = T>,
F2: Future<Output = T>, type Output = T;
where
F: Future<Output = Self::Output>,
fn or<F>(self, other: F) -> Or<Self, F>ⓘNotable traits for Or<F1, F2>impl<T, F1, F2> Future for Or<F1, F2> where
F1: Future<Output = T>,
F2: Future<Output = T>, type Output = T;
where
F: Future<Output = Self::Output>,
F1: Future<Output = T>,
F2: Future<Output = T>, type Output = T;
Returns the result of self
or other
future, preferring self
if both are ready. Read more
sourcefn race<F>(self, other: F) -> Race<Self, F>ⓘNotable traits for Race<F1, F2>impl<T, F1, F2> Future for Race<F1, F2> where
F1: Future<Output = T>,
F2: Future<Output = T>, type Output = T;
where
F: Future<Output = Self::Output>,
fn race<F>(self, other: F) -> Race<Self, F>ⓘNotable traits for Race<F1, F2>impl<T, F1, F2> Future for Race<F1, F2> where
F1: Future<Output = T>,
F2: Future<Output = T>, type Output = T;
where
F: Future<Output = Self::Output>,
F1: Future<Output = T>,
F2: Future<Output = T>, type Output = T;
Returns the result of self
or other
future, with no preference if both are ready. Read more
sourcefn catch_unwind(self) -> CatchUnwind<Self>ⓘNotable traits for CatchUnwind<F>impl<F> Future for CatchUnwind<F> where
F: Future + UnwindSafe, type Output = Result<<F as Future>::Output, Box<dyn Any + Send + 'static, Global>>;
where
Self: UnwindSafe,
fn catch_unwind(self) -> CatchUnwind<Self>ⓘNotable traits for CatchUnwind<F>impl<F> Future for CatchUnwind<F> where
F: Future + UnwindSafe, type Output = Result<<F as Future>::Output, Box<dyn Any + Send + 'static, Global>>;
where
Self: UnwindSafe,
F: Future + UnwindSafe, type Output = Result<<F as Future>::Output, Box<dyn Any + Send + 'static, Global>>;
Catches panics while polling the future. Read more
sourcefn boxed<'a>(
self
) -> Pin<Box<dyn Future<Output = Self::Output> + Send + 'a, Global>>ⓘNotable traits for Pin<P>impl<P> Future for Pin<P> where
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
where
Self: 'a + Send,
fn boxed<'a>(
self
) -> Pin<Box<dyn Future<Output = Self::Output> + Send + 'a, Global>>ⓘNotable traits for Pin<P>impl<P> Future for Pin<P> where
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
where
Self: 'a + Send,
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
Boxes the future and changes its type to dyn Future + Send + 'a
. Read more
sourcefn boxed_local<'a>(
self
) -> Pin<Box<dyn Future<Output = Self::Output> + 'a, Global>>ⓘNotable traits for Pin<P>impl<P> Future for Pin<P> where
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
where
Self: 'a,
fn boxed_local<'a>(
self
) -> Pin<Box<dyn Future<Output = Self::Output> + 'a, Global>>ⓘNotable traits for Pin<P>impl<P> Future for Pin<P> where
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
where
Self: 'a,
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
Boxes the future and changes its type to dyn Future + 'a
. Read more
sourceimpl<F> IntoFuture for F where
F: Future,
impl<F> IntoFuture for F where
F: Future,
type Output = <F as Future>::Output
type Output = <F as Future>::Output
into_future
)The output that the future will produce on completion.
type IntoFuture = F
type IntoFuture = F
into_future
)Which kind of future are we turning this into?
sourcefn into_future(self) -> <F as IntoFuture>::IntoFuture
fn into_future(self) -> <F as IntoFuture>::IntoFuture
into_future
)Creates a future from a value.