Crate local_pool_with_id

local-pool-with-id

A minor variation on a LocalPool executor which exposes unique IDs for tracking future completion.

This should almost be a drop in replacement for the existing LocalPool. All existing traits are still implemented. There are two API differences:

1. New (Local)SpawnWithId traits have been implemented. These accept the same arguments as their non-ID counterparts but return a unique ID that can be used to identify whether a spawned future has been completed.
2. try_run_one now returns an Option<usize> instead of a boolean. This usize will correspond to the ID received from the previous APIs and can be used with external tracking mechanism to know if a future is complete.

Motivation

The existing LocalPool allowed you to run all futures, opaquely, in a non-blocking way or to, blockingly, run a single future to completion and retrieve it’s output. By providing tracking IDs, we can use an external lookup to infer which futures are finished and ask them for their results directly.

Example

use local_pool_with_id::SpawnWithIdExt;
use futures::prelude::*;

let mut spawned_ids = std::collections::HashSet::new();
let mut pool = local_pool_with_id::LocalPool::new();
let spawner = pool.spawner();

let (id1, handle1) = spawner
    .spawn_with_handle(futures::future::ready(1i32))
    .unwrap();
let (id2, handle2) = spawner
    .spawn_with_handle(futures::future::ready(2u32))
    .unwrap();

spawned_ids.insert(id1);
spawned_ids.insert(id2);

while !spawned_ids.is_empty() {
    if let Some(completed) = pool.try_run_one() {
        assert!(spawned_ids.remove(&completed))
    }
}

assert_eq!(handle1.now_or_never().unwrap(), 1);
assert_eq!(handle2.now_or_never().unwrap(), 2);

Structs

LocalPool

A single-threaded task pool for polling futures to completion.

LocalSpawner

A handle to a LocalPool that implements Spawn.

Traits

LocalSpawnWithId

LocalSpawnWithIdExt

Extension trait for LocalSpawn.

SpawnWithId

SpawnWithIdExt

Extension trait for Spawn.