Crate commonware_parallel 

Parallelize fold operations with pluggable execution strategies.

This crate provides the Strategy trait, which abstracts over sequential and parallel execution of fold operations. This allows algorithms to be written once and executed either sequentially or in parallel depending on the chosen strategy.

Overview

The core abstraction is the Strategy trait, which provides several operations:

Core Operations:

• run: Chooses between serial and parallel operation bodies
• run_batches: Runs an operation over batches of its input
• run_tiles: Runs an operation over tiles of several passes over the same input
• fold: Reduces a collection to a single value
• try_fold: Like fold, but stops applying the fold operation after failures
• fold_init: Like fold, but with per-partition initialization
• sort_by: Sorts a slice with a comparator
• sort_unstable_by: Like sort_by, but without preserving the order of equal elements

Convenience Methods:

• map_collect_vec: Maps elements and collects into a Vec
• try_map_collect_vec: Maps fallible operations and collects into a Result<Vec<_>, _>
• map_init_collect_vec: Like map_collect_vec with per-partition initialization
• map_partition_collect_vec: Maps elements, collecting successful results and tracking indices of filtered elements

Two implementations are provided:

• Sequential: Executes operations sequentially on the current thread (works in no_std)
• Rayon: Adaptively executes collection operations serially or with a Commonware thread pool (requires std)

Features

• std (default): Enables the Rayon strategy and its thread pool
• test-utils: Enables mocks, strategies that pin or explore a test’s execution shapes

When the std feature is disabled, only Sequential is available, making this crate suitable for no_std environments.

Example

The main benefit of this crate is writing algorithms that can switch between sequential and parallel execution:

use commonware_parallel::{Strategy, Sequential};

fn sum_of_squares(strategy: &impl Strategy, data: &[i64]) -> i64 {
    strategy.fold(
        data,
        || 0i64,
        |acc, &x| acc + x * x,
        |a, b| a + b,
    )
}

let strategy = Sequential;
let data = vec![1, 2, 3, 4, 5];
let result = sum_of_squares(&strategy, &data);
assert_eq!(result, 55); // 1 + 4 + 9 + 16 + 25

Modules

rayon

A work-stealing pool of worker threads.

Structs

Batches

Batches supplied for one invocation of Strategy::run_batches.

Grid

A grid that Strategy::run_tiles can cut, made of rows passes over the run’s columns. Finishing a tile costs a fixed tile_cost cells.

Rayon

A parallel execution strategy backed by a Commonware thread pool.

Sequential

A sequential execution strategy.

Tiles

Tiles supplied for one invocation of Strategy::run_tiles.

Traits

Strategy

A strategy for executing fold operations.

Type Aliases

ThreadPool

A shared rayon::ThreadPool.