Struct Job 

pub struct Job<T> { /* private fields */ }

Work running on a worker thread, and its result once it’s done.

Start it with Job::spawn, then check Job::take each frame: the game keeps running meanwhile. GPU work (making meshes, textures) belongs on the game’s thread, after the job; building the data for it (heights, MeshData, decoded images) belongs in the job. In a browser, which has no threads here, the work runs when it’s spawned.

let mut job = Job::spawn(|| (1..=10).sum::<i32>());
// Each frame, until it's done:
let sum = loop {
    if let Some(sum) = job.take() {
        break sum;
    }
};
assert_eq!(sum, 55);

Implementations

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

pub fn spawn(work: impl FnOnce() -> T + Send + 'static) -> Self

Starts work on a worker thread (the shared pool, one thread per core).

let heights = Job::spawn(|| vec![0.0f32; 129 * 129]);
assert_eq!(heights.wait().len(), 129 * 129);

Examples found in repository

examples/streaming.rs (line 129)

fn main() {
    let bench = std::env::var("BENCH").is_ok();
    let shot = std::env::var("SHOT").ok();
    let mut cells = CellStreamer::new(TILE, LOAD, KEEP);
    let mut tiles: HashMap<(i32, i32), Tile> = HashMap::new();
    let mut ground: Option<Material> = None;
    let (mut yaw, mut speed, mut altitude) = (0.4f32, if bench { 600.0f32 } else { 120.0 }, 90.0f32);
    // The streaming's cost on the game's thread, for BENCH.
    let (mut uploaded, mut freed, mut upload_time, mut worst_upload) = (0usize, 0usize, 0.0f64, 0.0f64);
    Game::new("Crabby Engine: streaming", 1280, 720)
        .vsync(!bench)
        .system(move |ctx: &mut Ctx| {
            if ctx.key_pressed(Key::Escape) {
                ctx.quit();
            }
            let dt = ctx.dt();
            if ctx.key_down(Key::Left) {
                yaw += dt * 0.8;
            }
            if ctx.key_down(Key::Right) {
                yaw -= dt * 0.8;
            }
            if ctx.key_down(Key::W) {
                speed = (speed + 80.0 * dt).min(600.0);
            }
            if ctx.key_down(Key::S) {
                speed = (speed - 80.0 * dt).max(0.0);
            }
            if ctx.key_down(Key::E) {
                altitude += 40.0 * dt;
            }
            if ctx.key_down(Key::Q) {
                altitude = (altitude - 40.0 * dt).max(5.0);
            }
            // Fly on, keeping above the hills ahead.
            let rotation = Quat::from_rotation_y(yaw);
            let mut at = ctx.camera3d.position + rotation * Vec3::NEG_Z * speed * dt;
            let ahead = at + rotation * Vec3::NEG_Z * 120.0;
            let floor = height(at.x, at.z).max(height(ahead.x, ahead.z));
            at.y += (floor + altitude - at.y) * (dt * 1.5).min(1.0);
            ctx.camera3d.position = at;
            ctx.camera3d.rotation = rotation * Quat::from_rotation_x(-0.22);

            // Which tiles to start and drop.
            cells.update(at, STARTS);
            for &cell in cells.to_load() {
                let corner = cells.corner(cell);
                tiles.insert(cell, Tile::Building(Job::spawn(move || tile_data(corner))));
            }
            for cell in cells.to_drop() {
                // A job still building is dropped with its result.
                if let Some(Tile::Live(entity, tile)) = tiles.remove(cell) {
                    ctx.world.despawn(entity);
                    ctx.free_terrain_tile(tile);
                    freed += 1;
                }
            }
            // Finished tiles go on the GPU, a few a frame.
            let ground = *ground.get_or_insert_with(|| {
                let shader = ctx.create_shader("ground", GROUND);
                ctx.create_material(MaterialDesc {
                    shader: Some(shader),
                    ..MaterialDesc::color(Color::WHITE)
                })
            });
            let mut uploads = 0;
            for (&cell, tile) in tiles.iter_mut() {
                if uploads == UPLOADS {
                    break;
                }
                if let Tile::Building(job) = tile
                    && let Some(data) = job.take()
                {
                    let start = Instant::now();
                    let made = ctx.upload_terrain_tile(&data, ground);
                    let entity = ctx.world.spawn((Transform3D::at(cells.corner(cell)), made));
                    let took = start.elapsed().as_secs_f64() * 1000.0;
                    upload_time += took;
                    worst_upload = worst_upload.max(took);
                    uploaded += 1;
                    uploads += 1;
                    *tile = Tile::Live(entity, made);
                }
            }

            if ctx.frame() == 400
                && let Some(path) = &shot
            {
                ctx.save_screenshot(path);
            }
            if ctx.frame() == 402 && shot.is_some() {
                ctx.quit();
            }
            if bench && ctx.frame() == 3000 {
                let live = tiles.values().filter(|t| matches!(t, Tile::Live(..))).count();
                println!(
                    "{uploaded} tiles uploaded ({:.2} ms each, worst {worst_upload:.2} ms), {freed} freed, {live} live; {:?}",
                    upload_time / uploaded.max(1) as f64,
                    ctx.render_stats()
                );
                ctx.quit();
            }
        })
        .run(move |ctx| {
            ctx.post.bloom = 0.08;
            ctx.lighting.sun_direction = Sky::sun_direction_at(15.5);
            ctx.lighting.shadow_distance = 500.0;
            ctx.camera3d.far = LOAD + TILE;
            // Fog thick enough that tiles appear behind it, not at an edge.
            ctx.sky.fog_density = 0.0007;
            ctx.sky.fog_height = 40.0;
            ctx.sky.fog_falloff = 90.0;
            ctx.camera3d.position = vec3(0.0, height(0.0, 0.0) + 60.0, 0.0);
        });
}

impl<T> Job<T>

pub fn is_done(&mut self) -> bool

Whether the work has finished (its result may already be taken).

let mut job = Job::spawn(|| 7);
while !job.is_done() {}
assert!(job.is_done());

pub fn take(&mut self) -> Option<T>

The result, once the work is done; None before then, and after it was taken. Never waits.

let mut job = Job::spawn(|| "ready");
while !job.is_done() {}
assert_eq!(job.take(), Some("ready"));
assert_eq!(job.take(), None);

Panics

If the work panicked.

Examples found in repository

examples/streaming.rs (line 153)

fn main() {
    let bench = std::env::var("BENCH").is_ok();
    let shot = std::env::var("SHOT").ok();
    let mut cells = CellStreamer::new(TILE, LOAD, KEEP);
    let mut tiles: HashMap<(i32, i32), Tile> = HashMap::new();
    let mut ground: Option<Material> = None;
    let (mut yaw, mut speed, mut altitude) = (0.4f32, if bench { 600.0f32 } else { 120.0 }, 90.0f32);
    // The streaming's cost on the game's thread, for BENCH.
    let (mut uploaded, mut freed, mut upload_time, mut worst_upload) = (0usize, 0usize, 0.0f64, 0.0f64);
    Game::new("Crabby Engine: streaming", 1280, 720)
        .vsync(!bench)
        .system(move |ctx: &mut Ctx| {
            if ctx.key_pressed(Key::Escape) {
                ctx.quit();
            }
            let dt = ctx.dt();
            if ctx.key_down(Key::Left) {
                yaw += dt * 0.8;
            }
            if ctx.key_down(Key::Right) {
                yaw -= dt * 0.8;
            }
            if ctx.key_down(Key::W) {
                speed = (speed + 80.0 * dt).min(600.0);
            }
            if ctx.key_down(Key::S) {
                speed = (speed - 80.0 * dt).max(0.0);
            }
            if ctx.key_down(Key::E) {
                altitude += 40.0 * dt;
            }
            if ctx.key_down(Key::Q) {
                altitude = (altitude - 40.0 * dt).max(5.0);
            }
            // Fly on, keeping above the hills ahead.
            let rotation = Quat::from_rotation_y(yaw);
            let mut at = ctx.camera3d.position + rotation * Vec3::NEG_Z * speed * dt;
            let ahead = at + rotation * Vec3::NEG_Z * 120.0;
            let floor = height(at.x, at.z).max(height(ahead.x, ahead.z));
            at.y += (floor + altitude - at.y) * (dt * 1.5).min(1.0);
            ctx.camera3d.position = at;
            ctx.camera3d.rotation = rotation * Quat::from_rotation_x(-0.22);

            // Which tiles to start and drop.
            cells.update(at, STARTS);
            for &cell in cells.to_load() {
                let corner = cells.corner(cell);
                tiles.insert(cell, Tile::Building(Job::spawn(move || tile_data(corner))));
            }
            for cell in cells.to_drop() {
                // A job still building is dropped with its result.
                if let Some(Tile::Live(entity, tile)) = tiles.remove(cell) {
                    ctx.world.despawn(entity);
                    ctx.free_terrain_tile(tile);
                    freed += 1;
                }
            }
            // Finished tiles go on the GPU, a few a frame.
            let ground = *ground.get_or_insert_with(|| {
                let shader = ctx.create_shader("ground", GROUND);
                ctx.create_material(MaterialDesc {
                    shader: Some(shader),
                    ..MaterialDesc::color(Color::WHITE)
                })
            });
            let mut uploads = 0;
            for (&cell, tile) in tiles.iter_mut() {
                if uploads == UPLOADS {
                    break;
                }
                if let Tile::Building(job) = tile
                    && let Some(data) = job.take()
                {
                    let start = Instant::now();
                    let made = ctx.upload_terrain_tile(&data, ground);
                    let entity = ctx.world.spawn((Transform3D::at(cells.corner(cell)), made));
                    let took = start.elapsed().as_secs_f64() * 1000.0;
                    upload_time += took;
                    worst_upload = worst_upload.max(took);
                    uploaded += 1;
                    uploads += 1;
                    *tile = Tile::Live(entity, made);
                }
            }

            if ctx.frame() == 400
                && let Some(path) = &shot
            {
                ctx.save_screenshot(path);
            }
            if ctx.frame() == 402 && shot.is_some() {
                ctx.quit();
            }
            if bench && ctx.frame() == 3000 {
                let live = tiles.values().filter(|t| matches!(t, Tile::Live(..))).count();
                println!(
                    "{uploaded} tiles uploaded ({:.2} ms each, worst {worst_upload:.2} ms), {freed} freed, {live} live; {:?}",
                    upload_time / uploaded.max(1) as f64,
                    ctx.render_stats()
                );
                ctx.quit();
            }
        })
        .run(move |ctx| {
            ctx.post.bloom = 0.08;
            ctx.lighting.sun_direction = Sky::sun_direction_at(15.5);
            ctx.lighting.shadow_distance = 500.0;
            ctx.camera3d.far = LOAD + TILE;
            // Fog thick enough that tiles appear behind it, not at an edge.
            ctx.sky.fog_density = 0.0007;
            ctx.sky.fog_height = 40.0;
            ctx.sky.fog_falloff = 90.0;
            ctx.camera3d.position = vec3(0.0, height(0.0, 0.0) + 60.0, 0.0);
        });
}

pub fn wait(self) -> T

Waits for the result, blocking this thread (for loading screens and tests; a game’s frames shouldn’t wait).

assert_eq!(Job::spawn(|| 2 + 2).wait(), 4);

Panics

If the work panicked, or its result was already taken.

Trait Implementations

impl<T: Debug> Debug for Job<T>

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

Formats the value using the given formatter.