Crate computation_process 

Computation process

A Rust library for defining stateful computations (and generators) that support suspend/resume, interleaving, cancellation, and serialization.

This crate does not use unsafe.

Overview

This library provides abstractions for defining “long-running” computations. The concepts are similar to asynchronous code but offer features that were never a priority in async programming. The target audience are projects that implement CPU-intensive, long-running computations but require granular control over the computation state.

Key Features

• Cancellation: Each computation can be forcefully stopped using cooperative cancellation (compatible with the cancel-this crate).
• Suspend/resume: A computation can define safe suspend points. During these points, it is safe to serialize, interleave, or otherwise “transfer” the computation.
• Interleaving: Suspend points allow safely interleaving multiple computations on a single thread with priority-based scheduling.
• Serialization: The state of each computation is isolated and can be saved/restored.

Core Concepts

• Completable<T>: A result type that can be incomplete (Suspended, Cancelled, or Exhausted).
• Computable<T>: A trait for objects that can be driven to completion by calling Computable::try_compute.
• Algorithm<CTX, STATE, T>: Extends Computable with access to context and state.
• Generatable<T>: Like Computable, but produces a stream of values.
• GenAlgorithm<CTX, STATE, T>: Extends Generatable with context and state.
• Computation and Generator: Default implementations using step functions.

Quick Example

use computation_process::{Computation, ComputationStep, Completable, Incomplete, Computable, Stateful};

struct CountingStep;

impl ComputationStep<u32, u32, u32> for CountingStep {
    fn step(target: &u32, count: &mut u32) -> Completable<u32> {
        *count += 1;
        if *count >= *target {
            Ok(*count)
        } else {
            Err(Incomplete::Suspended)
        }
    }
}

let mut computation = Computation::<u32, u32, u32, CountingStep>::from_parts(5, 0);
let result = computation.compute().unwrap();
assert_eq!(result, 5);

Structs

Collector

A Computable that collects all items from a Generatable into a collection.

ComputableIdentity

A trivial Computable that immediately returns a pre-computed value.

ComputableResult

A result-like object that stores the result of a Computable for later use.

Computation

A stateful computation that can be suspended and resumed.

Generator

A stateful generator that can be suspended and resumed.

Enums

Incomplete

The error type returned by an algorithm when the result is not (yet) available.

Traits

Algorithm

Extends Computable trait with immutable CONTEXT and mutable STATE.

Computable

A generic trait implemented by types that represent a “computation”.

ComputationStep

Defines a single step of a Computation.

GenAlgorithm

Extends Generatable trait with immutable CONTEXT and mutable STATE.

Generatable

An alternative to crate::Computable which is intended for generators.

GeneratorStep

Defines a single step of a Generator.

Stateful

A shared interface of objects that provide access to an immutable CONTEXT and mutable STATE.

Type Aliases

Completable

A Completable result is a value eventually computed by an algorithm where the computation can be Incomplete when the value is polled.

DynAlgorithm

A type alias for Box<dyn Algorithm<CONTEXT, STATE, OUTPUT>>.

DynComputable

A type alias for Box<dyn Computable<T>>.

DynGenAlgorithm

A type alias for Box<dyn GenAlgorithm<CONTEXT, STATE, OUTPUT>>.

DynGeneratable

A type alias for Box<dyn Generatable<T>>.