Struct coffee::load::Task

pub struct Task<T> { /* fields omitted */ }

A Task<T> represents an operation that produces a value of type T.

Laziness

A Task is a recipe that describes how to produce a specific output, like a function. They can be combined or transformed in certain ways and run whenever needed.

Creating a Task consists in specifying this recipe. For instance, we could define a task to load an Image like this:

let load_image = Task::using_gpu(|gpu| Image::new(gpu, "my-image.png"));

Here we just describe how to load an image, we do not load it right away. This is how Image::load works, you should use that instead of writing this over and over!

Composition

Tasks can be combined thanks to the Join trait.

Let's say we have a Task<Image> and a Task<TextureArray>, we can obtain a Task<(Image, TextureArray)> like this:

use coffee::load::Join;

let combined_task = (load_image, load_texture_array).join();

You can do this for up to 8 tasks. However, consider grouping task output in meaningful structs using map:

use coffee::load::Join;

pub struct PlayerAssets {
    idle: Image,
    running: Image,
}

impl PlayerAssets {
    pub fn load() -> Task<PlayerAssets> {
        (
            Image::load("player/idle.png"),
            Image::load("player/running.png"),
        )
            .join()
            .map(|(idle, running)| PlayerAssets { idle, running })
    }
}

Implementations

impl<T> Task<T>

pub fn new<F>(f: F) -> Task<T> where
    F: 'static + FnOnce() -> Result<T>, 

Creates a new Task from a lazy operation.

Imagine we had to generate a random game map, we could represent this as a Task:

struct Map {
    // ...
}

impl Map {
    pub fn generate() -> Map {
        Map { /*...*/ }
    }
}

let generate_map = Task::new(|| Ok(Map::generate()));

pub fn succeed<F>(f: F) -> Task<T> where
    F: 'static + FnOnce() -> T, 

Creates a new Task from a lazy operation that cannot fail.

struct Map {
    // ...
}

impl Map {
    pub fn generate() -> Map {
        Map { /*...*/ }
    }
}

let generate_map = Task::succeed(Map::generate);

pub fn using_gpu<F>(f: F) -> Task<T> where
    F: 'static + FnOnce(&mut Gpu) -> Result<T>, 

Creates a new Task that uses a Gpu.

You can use this to load and prepare graphical assets.

Keep in mind that many types in graphics already implement loading methods returning a Task (like Image::load or Font::load_from_bytes). Before using this, check out whether whatever you want to load has already a useful helper that suits your needs!

pub fn stage<S: Into<String>>(title: S, task: Task<T>) -> Task<T> where
    T: 'static, 

Adds a title to the Task.

The title will be used when reporting progress once the Task is run. This allows task runners, like loading screens, to show additional feedback to the user.

For example, let's say we want to generate a map and load some terrain assets. We can define a couple stages for each task:

use coffee::load::Join;

let load_game =
    (
        Task::stage("Generating map...", Task::succeed(Map::generate)),
        Task::stage("Loading terrain...", TerrainAssets::load())
    )
        .join();

If we then used this Task with the ProgressBar loading screen, it would show each of these titles on top of the progress bar when their according tasks are being run.

pub fn total_work(&self) -> u32

Returns the total units of work of the Task.

pub fn map<F, A>(self, f: F) -> Task<A> where
    T: 'static,
    F: 'static + FnOnce(T) -> A, 

Transforms the output of a Task.

As explained above, use this method to make your tasks return your own custom types, enhancing composability.

pub fn run(self, gpu: &mut Gpu) -> Result<T>

Runs a Task and obtains the produced value.

Trait Implementations

impl<T> Debug for Task<T>

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

Formats the value using the given formatter.