Trait Lanes

Source

pub trait Lanes {
    type Lane<'l>;
    type Error: Error + Send + Sync + 'static;

    // Required methods
    fn lane_count(&self) -> usize;
    fn run<E: Send>(
        &mut self,
        lane: impl Fn(usize, &mut Self::Lane<'_>, &LaneControl<'_>) -> Result<(), E> + Sync,
    ) -> Result<(), LanesError<E, Self::Error>>;
    fn run_with_coordinator<C, E: Send>(
        &mut self,
        coordinator: impl FnOnce(&LaneControl<'_>) -> Result<C, E>,
        lane: impl Fn(usize, &mut Self::Lane<'_>, &LaneControl<'_>) -> Result<(), E> + Sync,
    ) -> Result<C, LanesError<E, Self::Error>>;
}

Expand description

A per-worker execution lanes executor plus a caller-thread coordinator.

The trait is implemented by execution backends; it has no Send, Sync, or 'static supertrait, so an executor, its lane resources, a coordinator capture, and a coordinator result may all stay on one thread. Lane closures are shared across the lanes and therefore require Sync.

Both methods join every lane before returning, and resume a lane panic only after that join. Lanes observe cancellation through LaneControl and must stop when it is cancelled; the executor cancels the control after the coordinator returns. An executor whose backend can stop a run without reaching a lane callback lends the side that waits on cancellation a LaneControl::with_probe view, so that wait also observes the backend’s own stop signal.

§Example

use hataori::{map_in_lanes, Domain, LocalMode, RayonLanes};
use std::sync::Arc;

let pool = Arc::new(rayon::ThreadPoolBuilder::new().num_threads(2).build().unwrap());
let domain = Domain::external(Arc::clone(&pool), vec![0, 1], 2).unwrap();
let mut lanes = RayonLanes::new(&domain).unwrap();
let doubled = map_in_lanes(&mut lanes, vec![1, 2, 3], |item, ()| {
    Ok::<_, std::convert::Infallible>(item * 2)
})
.unwrap();
assert_eq!(doubled, vec![2, 4, 6]);

Required Associated Types§

Source

type Lane<'l>

The execution resource lent to one lane callback.

Source

type Error: Error + Send + Sync + 'static

A lane entry, join, or cleanup failure.

Required Methods§

Source

fn lane_count(&self) -> usize

Returns the number of lanes the executor runs.

Source

fn run<E: Send>( &mut self, lane: impl Fn(usize, &mut Self::Lane<'_>, &LaneControl<'_>) -> Result<(), E> + Sync, ) -> Result<(), LanesError<E, Self::Error>>

Runs lane on every lane, joins all of them, then resumes a lane panic.

§Errors

A lane error or panic cancels the shared control immediately, so cooperatively waiting lanes are released before the join. Returns LanesError::Lane when a lane callback returns an error, LanesError::Executor when the executor itself cannot run or join a lane, or LanesError::SingleLane when the executor has no lane to run. A lane panic is resumed after the join and takes precedence over a lane error.

Source

fn run_with_coordinator<C, E: Send>( &mut self, coordinator: impl FnOnce(&LaneControl<'_>) -> Result<C, E>, lane: impl Fn(usize, &mut Self::Lane<'_>, &LaneControl<'_>) -> Result<(), E> + Sync, ) -> Result<C, LanesError<E, Self::Error>>

Runs coordinator on the calling thread concurrently with every lane.

The coordinator is not a lane: it gets no lane resource. Lanes and the coordinator communicate only through caller-owned synchronization. When the coordinator returns, errors, or panics, the control is cancelled and every lane is joined before this method returns.

An executor that cannot overlap a coordinator with its lanes returns LanesError::SingleLane without running either callback, so the caller can fall back to a non-concurrent path explicitly. An executor that rejects being driven from one of its own workers returns LanesError::Reentrant before running either callback.

§Errors

Returns LanesError::SingleLane for a non-concurrent executor, LanesError::Reentrant for entry from one of the executor’s own workers, LanesError::Coordinator when the coordinator returns an error, LanesError::Lane when a lane callback returns an error, or LanesError::Executor when the executor cannot run or join a lane. A lane panic is resumed after the join and takes precedence over every ordinary error.