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

Methods

impl<T> Task<T>

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

Create 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(Map::generate);

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

Create a new task that uses the 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). 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, 

Add a title to a 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::new(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

Get the total units of work of the task.

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

Transform 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<F>(self, window: &mut Window, on_progress: F) -> Result<T> where
    F: FnMut(&Progress, &mut Window), 

Run a task and obtain the produced value.

You can provide a function to keep track of Progress.

As of now, this method needs a Window because tasks are mostly meant to be used with loading screens. However, the Task abstraction is generic enough to be useful in other scenarios and we could work on removing this dependency. If you have a particular use case for them, feel free to open an issue detailing it!

Trait Implementations

impl<T> Debug for Task<T>

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

Formats the value using the given formatter.