Struct Task 

pub struct Task<T, M = ()> { /* private fields */ }

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

impl<T, M> Task<T, M>

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();

Examples found in repository

examples/async_tasks/async_channel_pattern.rs (line 61)

fn spawn_tasks(channel: Res<CubeChannel>) {
    let pool = AsyncComputeTaskPool::get();

    for x in -NUM_CUBES..NUM_CUBES {
        for z in -NUM_CUBES..NUM_CUBES {
            let sender = channel.sender.clone();
            // Spawn a task on the async compute pool
            pool.spawn(async move {
                let delay = Duration::from_secs_f32(rand::rng().random_range(2.0..8.0));
                // Simulate a delay before task completion
                Delay::new(delay).await;
                let _ = sender.send(CubeFinished {
                    transform: Transform::from_xyz(x as f32, 0.5, z as f32),
                });
            })
            .detach();
        }
    }
}

examples/asset/asset_saving.rs (line 62)

fn perform_save(
    image_to_save: Res<ImageToSave>,
    images: Res<Assets<Image>>,
    asset_server: Res<AssetServer>,
) {
    let image = images.get(&image_to_save.0).unwrap();

    let image = image.clone();
    let asset_server = asset_server.clone();
    IoTaskPool::get()
        .spawn(async move {
            match save_using_saver(
                asset_server.clone(),
                &ImageSaver,
                &ASSET_PATH.into(),
                SavedAsset::from_asset(&image),
                &ImageSaverSettings::default(),
            )
            .await
            {
                Ok(()) => info!("Completed save of {ASSET_PATH}"),
                Err(err) => error!("Failed to save asset: {err}"),
            }
        })
        .detach();
}

examples/asset/multi_asset_sync.rs (line 170)

fn setup_assets(mut commands: Commands, asset_server: Res<AssetServer>) {
    let (barrier, guard) = AssetBarrier::new();
    commands.insert_resource(OneHundredThings(std::array::from_fn(|i| {
        let builder = asset_server.load_builder().with_guard(guard.clone());
        match i % 5 {
            0 => builder.load("models/GolfBall/GolfBall.glb"),
            1 => builder.load("models/AlienCake/alien.glb"),
            2 => builder.load("models/AlienCake/cakeBirthday.glb"),
            3 => builder.load("models/FlightHelmet/FlightHelmet.gltf"),
            4 => builder.load("models/torus/torus.gltf"),
            _ => unreachable!(),
        }
    })));
    let future = barrier.wait_async();
    commands.insert_resource(barrier);

    let loading_state = Arc::new(AtomicBool::new(false));
    commands.insert_resource(AsyncLoadingState(loading_state.clone()));

    // await the `AssetBarrierFuture`.
    AsyncComputeTaskPool::get()
        .spawn(async move {
            future.await;
            // Notify via `AsyncLoadingState`
            loading_state.store(true, Ordering::Release);
        })
        .detach();
}

examples/asset/asset_saving_with_subassets.rs (line 86)

fn perform_save(boxes: Query<(&Sprite, &Transform), With<Box>>, asset_server: Res<AssetServer>) {
    // First we extract all the data needed to produce an asset we can save.
    let boxes = boxes
        .iter()
        .map(|(sprite, transform)| OneBox {
            position: transform.translation.xy(),
            color: sprite.color,
        })
        .collect::<Vec<_>>();

    let asset_server = asset_server.clone();
    IoTaskPool::get()
        .spawn(async move {
            // Build a `SavedAsset` instance from the boxes we extracted.
            let mut builder = SavedAssetBuilder::new(asset_server.clone(), ASSET_PATH.into());
            let mut many_boxes = ManyBoxes { boxes: vec![] };
            for (index, one_box) in boxes.iter().enumerate() {
                many_boxes
                    .boxes
                    .push(builder.add_labeled_asset_with_new_handle(
                        index.to_string(),
                        SavedAsset::from_asset(one_box),
                    ));
            }

            let saved_asset = builder.build(&many_boxes);
            // Save the asset using the provided saver.
            match save_using_saver(
                asset_server.clone(),
                &ManyBoxesSaver,
                &ASSET_PATH.into(),
                saved_asset,
                &(),
            )
            .await
            {
                Ok(()) => info!("Completed save of {ASSET_PATH}"),
                Err(err) => error!("Failed to save asset: {err}"),
            }
        })
        .detach();
}

examples/animation/animation_graph.rs (line 201)

fn setup_assets_programmatically(
    commands: &mut Commands,
    asset_server: &mut AssetServer,
    animation_graphs: &mut Assets<AnimationGraph>,
    _save: bool,
) {
    // Create the nodes.
    let mut animation_graph = AnimationGraph::new();
    let blend_node = animation_graph.add_blend(0.5, animation_graph.root);
    animation_graph.add_clip(
        asset_server.load(GltfAssetLabel::Animation(0).from_asset("models/animated/Fox.glb")),
        1.0,
        animation_graph.root,
    );
    animation_graph.add_clip(
        asset_server.load(GltfAssetLabel::Animation(1).from_asset("models/animated/Fox.glb")),
        1.0,
        blend_node,
    );
    animation_graph.add_clip(
        asset_server.load(GltfAssetLabel::Animation(2).from_asset("models/animated/Fox.glb")),
        1.0,
        blend_node,
    );

    // If asked to save, do so.
    #[cfg(not(target_arch = "wasm32"))]
    if _save {
        let animation_graph = animation_graph.clone();

        IoTaskPool::get()
            .spawn(async move {
                use std::io::Write;

                let animation_graph: SerializedAnimationGraph = animation_graph
                    .try_into()
                    .expect("The animation graph failed to convert to its serialized form");

                let serialized_graph =
                    ron::ser::to_string_pretty(&animation_graph, PrettyConfig::default())
                        .expect("Failed to serialize the animation graph");
                let mut animation_graph_writer = File::create(Path::join(
                    &FileAssetReader::get_base_path(),
                    Path::join(Path::new("assets"), Path::new(ANIMATION_GRAPH_PATH)),
                ))
                .expect("Failed to open the animation graph asset");
                animation_graph_writer
                    .write_all(serialized_graph.as_bytes())
                    .expect("Failed to write the animation graph");
            })
            .detach();
    }

    // Add the graph.
    let handle = animation_graphs.add(animation_graph);

    // Save the assets in a resource.
    commands.insert_resource(ExampleAnimationGraph(handle));
}

examples/scene/world_serialization.rs (line 214)

fn save_world_system(world: &mut World) {
    let asset_server = world.resource::<AssetServer>().clone();
    // The `TypeRegistry` resource contains information about all registered types (including components).
    // This is used to construct worlds, so we'll want to ensure that we use the registry from the
    // main world. To do this, we can simply clone the `AppTypeRegistry` resource.
    let type_registry = world.resource::<AppTypeRegistry>().clone();

    // Any ECS World can be serialized.
    // For demonstration purposes, we'll create a new one.
    let mut scene_world = World::new();

    let mut component_b = ComponentB::from_world(world);
    component_b.value = "hello".to_string();
    scene_world.spawn((
        component_b,
        ComponentA { x: 1.0, y: 2.0 },
        Transform::IDENTITY,
        Name::new("joe"),
        WorldAssetRoot(asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0")),
    ));
    scene_world.spawn(ComponentA { x: 3.0, y: 4.0 });
    scene_world.insert_resource(ResourceA { score: 1 });

    // With our sample world ready to go, we can now create a DynamicWorld from it.
    // For simplicity, we will create our scene using DynamicWorld directly, but if
    // you need more control, you can use DynamicWorldBuilder.
    let dynamic_world = DynamicWorld::from_world_with(&scene_world, &type_registry.read());

    // Dynamic Worlds can be serialized like this:
    let type_registry = world.resource::<AppTypeRegistry>();
    let type_registry = type_registry.read();
    let serialized_world = dynamic_world.serialize(&type_registry).unwrap();

    // Shows the serialized world in the console
    info!("{}", serialized_world);

    // Writing the world to a new file. Using a task to avoid calling the filesystem APIs in a system
    // as they are blocking.
    //
    // This can't work in Wasm as there is no filesystem access.
    #[cfg(not(target_arch = "wasm32"))]
    IoTaskPool::get()
        .spawn(async move {
            // Write the world RON data to file
            File::create(format!("assets/{NEW_WORLD_FILE_PATH}"))
                .and_then(|mut file| file.write(serialized_world.as_bytes()))
                .expect("Error while writing world to file");
        })
        .detach();
}

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;
});

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

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);

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.

pub fn metadata(&self) -> &M

Get the metadata associated with this task.

Tasks can be created with a metadata object associated with them; by default, this is a () value. See the [Builder::metadata()] method for more information.

Trait Implementations

impl<T, M> Debug for Task<T, M>

where M: Debug,

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

Formats the value using the given formatter.

impl<T, M> Drop for Task<T, M>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T, M> Future for Task<T, M>

type Output = T

The type of value produced on completion.

fn poll( self: Pin<&mut Task<T, M>>, cx: &mut Context<'_>, ) -> Poll<<Task<T, M> 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, M> RefUnwindSafe for Task<T, M>

Available on crate feature std only.

impl<T, M> Send for Task<T, M>

where T: Send, M: Send + Sync,

impl<T, M> Sync for Task<T, M>

where M: Send + Sync,

impl<T, M> Unpin for Task<T, M>

impl<T, M> UnwindSafe for Task<T, M>

Available on crate feature std only.