Struct switchyard::Switchyard

pub struct Switchyard<TD: 'static> { /* fields omitted */ }

Compute focused async executor.

See crate documentation for more details.

Implementations

impl<TD: 'static> Switchyard<TD>

pub fn new<TDFunc>(
    pool_count: Pool,
    thread_allocations: impl IntoIterator<Item = ThreadAllocationOutput>,
    thread_local_data_creation: TDFunc
) -> Result<Self, SwitchyardCreationError> where
    TDFunc: Fn() -> TD + Send + Sync + 'static, 

Create a new switchyard.

Will create pool_count job pools.

For each element in the provided thread_allocations iterator, the yard will spawn a worker thread with the given settings. Helper functions in threads can generate these iterators for common situations.

thread_local_data_creation will be called on each thread to create the thread local data accessible by spawn_local.

pub fn spawn<Fut, T>(
    &self,
    pool: Pool,
    priority: Priority,
    fut: Fut
) -> JoinHandle<T> where
    Fut: Future<Output = T> + Send + 'static,
    T: Send + 'static, 

Spawn a future which can migrate between threads during execution to the given job pool at the given priority.

A higher priority will cause the task to be run sooner.

Example

use switchyard::{Switchyard, threads::single_pool_single_thread};

// Create a yard with a single pool
let yard: Switchyard<()> = Switchyard::new(1, single_pool_single_thread(None, None), || ()).unwrap();

// Spawn a task on pool 0 and with priority 0 and get a handle to the result.
let handle = yard.spawn(0, 0, async move { 2 * 2 });

// Await result
assert_eq!(handle.await, 4);

Panics

• pool refers to a non-existent job pool.
• finish has been called on the pool.

pub fn spawn_local<Func, Fut, T>(
    &self,
    pool: Pool,
    priority: Priority,
    async_fn: Func
) -> JoinHandle<T> where
    Func: FnOnce(Arc<TD>) -> Fut + Send + 'static,
    Fut: Future<Output = T>,
    T: Send + 'static, 

Spawns an async function which is tied to a single thread during execution.

Spawns to the given job pool at the given priority.

The given async function will be provided an Arc to the thread-local data to create its future with.

A higher priority will cause the task to be run sooner.

The function must be Send, but the future returned by that function may be !Send.

Example

use std::{cell::Cell, sync::Arc};
use switchyard::{Switchyard, threads::single_pool_single_thread};

// Create a yard with thread local data.
let yard: Switchyard<Cell<u64>> = Switchyard::new(
    1,
    single_pool_single_thread(None, None),
    || Cell::new(42)
).unwrap();

// Spawn an async function using the data.
yard.spawn_local(0, 0, |data: Arc<Cell<u64>>| async move {data.set(12);});

async fn some_async(data: Arc<Cell<u64>>) -> u64 {
    data.set(15);
    2 * 2
}

// Works with normal async functions too
let handle = yard.spawn_local(0, 0, some_async);
assert_eq!(handle.await, 4);

Panics

• Panics is pool refers to a non-existent job pool.

pub async fn wait_for_idle(&self)

Wait until all working threads are starved of work due to lack of jobs or all jobs waiting.

Safety

• This function provides no safety guarantees.
• Jobs may be added while the future returns.
• Jobs may be woken while the future returns.

pub fn jobs(&self) -> usize

Current amount of jobs in flight.

Safety

• This function provides no safety guarantees.
• Jobs may be added after the value is received and before it is returned.

pub fn active_threads(&self) -> usize

Count of threads currently processing jobs.

Safety

• This function provides no safety guarantees.
• Jobs may be added after the value is received and before it is returned re-activating threads.

pub fn access_per_thread_data(&mut self) -> Option<Vec<&mut TD>> where
    TD: Send, 

Access the per-thread data of each thread. Only available if TD is Send.

This function requires &mut self in order to be sound. If you have the yard in a global, you need to wrap it with RwLock so you can get a &mut from a &.

Two conditions need to be true for this to return Some. First all threads must be idle (i.e. wait_for_idle’s future would immediately return). Second no references to any thread’s local data may be alive.

Example

use std::{cell::Cell, sync::Arc};
use switchyard::{Switchyard, threads::single_pool_single_thread};

// Create a yard with thread local data.
let mut yard: Switchyard<Cell<u64>> = Switchyard::new(
    1,
    single_pool_single_thread(None, None),
    || Cell::new(42)
).unwrap();

// Wait for all threads to get themselves situated.
yard.wait_for_idle().await;

// View that thread-local data. The yard has one thread, so returns a vec of length one.
assert_eq!(yard.access_per_thread_data(), Some(vec![&mut Cell::new(42)]));

// Launch a task to change that data
let handle = yard.spawn_local(0, 0, |data| async move { data.set(525_600); });

// If the task isn't finished yet, this will return None.
yard.access_per_thread_data();

// Wait for task to be done
assert_eq!(handle.await, ());

// We also need to wait for all threads to come to a stopping place
yard.wait_for_idle().await;

// Observe changed value
assert_eq!(yard.access_per_thread_data(), Some(vec![&mut Cell::new(525_600)]));

Safety

• This function guarantees that there exist no other references to this data if Some is returned.
• This function guarantees that jobs() is 0 and will stay zero while the returned references are still live.

pub fn finish(&mut self)

Kill all threads as soon as they finish their jobs. All calls to spawn and spawn_local will panic after this function is called.

This is equivalent to calling drop. Calling this function twice will be a no-op the second time.

Trait Implementations

impl<TD: 'static> Drop for Switchyard<TD>

fn drop(&mut self)

Executes the destructor for this type.

impl<TD> Send for Switchyard<TD>

impl<TD> Sync for Switchyard<TD>