exec-rs

Rust port of the corresponding kotlin lib.

Library that provides utility traits for task execution and, if the sync feature is enabled, the ability to synchronise tasks based on the value of a key.

Installation

To add exec-rs to your project simply add the following Cargo dependency:

[dependencies]
exec-rs = "0.1.2"

Or to exclude the "sync" feature:

[dependencies.exec-rs]
version = "0.1.2"
default-features = false

Executors

Provides two different types that can manage task execution depending on the use case.

Invoker

pub trait Invoker {

    fn pre_invoke(&self);

    fn invoke_with_mode<'f, T: 'f, F: FnOnce() -> T + 'f>(
        &'f self,
        mode: &'f Mode<'f, T>,
        task: F,
    ) -> T;

    fn invoke<'f, T: 'f, F: FnOnce() -> T + 'f>(&'f self, task: F) -> T;

    fn invoke_with_mode_optional<'f, T: 'f, F: FnOnce() -> T + 'f>(
        &'f self,
        mode: Option<&'f Mode<'f, T>>,
        task: F,
    ) -> T;

    fn do_invoke<'f, T: 'f, F: FnOnce() -> T + 'f>(
        &'f self,
        mode: Option<&'f Mode<'f, T>>,
        task: F,
    ) -> T;

    fn post_invoke(&self);

    fn invoke_post_invoke_on_panic(&self) -> bool;

    fn and_then<I: Invoker>(self, inner: I) -> CombinedInvoker<Self, I>;
}

Trait that may be implemented for types that manage executing a task that do not care about the return type of the task. Implementors may simply override pre_invoke and post_invoke to run code before or / and after invoking a task or override do_invoke to control exactly how a task is invoked, by default this simply calls the task if no mode was supplied or calls crate::invoke if a mode was supplied.

Calling pre_invoke and post_invoke is managed by invoke_with_mode_optional which is the function used by both invoke_with_mode and invoke and internally calls do_invoke. So if implementors override invoke_with_mode_optional they either must manage calling pre_invoke and post_invoke or not use these functions.

Mode

The Mode API consists of 3 parts: Mode, ModeWrapper and ModeCombiner.

Mode

pub struct Mode<'m, T: 'm> {
    mode_combiner: Option<Box<dyn ModeCombiner<'m, T> + 'm>>,
}

Struct that manages collecting and combining ModeWrapper. This is the type supplied when submitting tasks in order to apply ModeWrappers.

Modes may be used by implementing the ModeWrapper trait to be able to wrap tasks in an enclosing function. Unlike Invokers, Modes and ModeWrappers are generic over the return type of the tasks they may wrap and thus can directly interact with the return value of the task. This also means that the lifetime of the Mode is tied to the lifetime of the type they are generic over.

ModeWrapper

pub trait ModeWrapper<'m, T: 'm> {

    fn wrap(self: Arc<Self>, task: Box<dyn FnOnce() -> T + 'm>) -> Box<dyn FnOnce() -> T + 'm>;

    fn into_combiner(self) -> Box<dyn ModeCombiner<'m, T> + 'm>;
}

Trait to implement in order to apply a mode to a task. ModeWrappers are supplied to a Mode using Mode::with where they might be combined with other ModeWrappers using the ModeCombiner supplied by ModeWrapper::into_combiner. Unlike Invokers, Modes and ModeWrappers are generic over the return type of the tasks they may wrap and thus can directly interact with the return value of the task. This also means that the lifetime of the Mode is tied to the lifetime of the type they are generic over.

ModeCombiner

pub trait ModeCombiner<'m, T: 'm> {

    fn combine(
        &self,
        other: Box<dyn ModeCombiner<'m, T> + 'm>,
    ) -> Box<dyn ModeCombiner<'m, T> + 'm>;

    fn get_outer(&self) -> Option<&dyn ModeCombiner<'m, T>>;

    fn set_outer(&mut self, outer: Arc<dyn ModeCombiner<'m, T> + 'm>);

    fn iter<'a>(&'a self) -> ModeCombinerIterator<'a, 'm, T>;

    fn wrapper_ref(&self) -> Arc<dyn ModeWrapper<'m, T> + 'm>;
}

Trait used to combine ModeWrappers by allowing one ModeWrapper to delegate to another ModeWrapper and providing an iterator that can unwrap combined ModeWrappers. An implementation of this trait is returned by ModeWrapper::into_combiner which returns a DelegatingModeCombiner by default.

Sync

The sync module provides the MutexSync struct which can be used to execute and synchronise tasks by the value of the key provided when submitting a task.

pub struct MutexSync<K>
where
    K: 'static + Sync + Send + Clone + Hash + Ord,
{
    mutex_map: flurry::HashMap<K, ReferenceCountedMutex<K>>,
}

impl<K> MutexSync<K>
where
    K: 'static + Sync + Send + Clone + Hash + Ord,
{
    pub fn new() -> Self;

    pub fn evaluate<R, F: FnOnce() -> R>(&self, key: K, task: F) -> R;
}

Task executor that can synchronise tasks by value of a key provided when submitting a task.

For example, if i32 is used as key type, then tasks submitted with keys 3 and 5 may run concurrently but several tasks submitted with key 7 are synchronised by a mutex mapped to the key.

Manages a concurrent hash map that maps ReferenceCountedMutex elements to the used keys. The ReferenceCountedMutex struct holds a mutex used for synchronisation and removes itself from the map automatically if not used by any thread anymore by managing an atomic reference counter. If the counter is decremented from 1 to 0 the element is removed from the map and the counter cannot be incremented back up again. If the counter reached 0 future increments fail and a new ReferenceCountedMutex is created instead. When creating a new ReferenceCountedMutex and inserting it to the map fails because another thread has already created an element for the same key, the current thread tries to use the found existing element instead as long as its reference counter is valid (greater than 0), else it retries creating the element.

The type of the key used for synchronisation must be able to be used as a key for the map and thus must implement Sync + Send + Clone + Hash + Ord and have a static lifetime.