orx-parallel

The library provides first-class support for fallible parallel flows. You can transform a pipeline to handle Option<T> or Result<T, E> types, allowing you to write only the success path. Any failure in the pipeline will cause an early exit (short-circuiting).

• Use .into_optional() for Option<T> pipelines.
• Use .into_fallible() for Result<T, E> pipelines.

use orx_parallel::*;

fn total_price(rows: &[&str]) -> Option<u64> {
    rows.par()
        .map(|row| parse_qty_and_price(row)) // ← some might return None
        .into_optional() // ← ascend
        .filter(|(qty, _)| *qty >= 2) // ← focus only on success path
        .map(|(qty, unit_price)| qty * unit_price) // ← success path
        .sum()
}

The WASM support is split into three distinct layers to separate computation logic from browser-specific orchestration:

1. orx-parallel (The Core): Owns the scheduling logic, task queues, and the WasmWebPool implementation.
2. wasm_bindings (The Bridge): A thin layer exposing the initialization API (e.g., init_wasm_parallel_runtime) to the JavaScript boundary.
3. orx-parallel-wasm (The Orchestrator): Manages the browser-side complexity, including ParallelWorker clients, bundler adapters, and asset preparation for workers.
4. The Browser Host: Responsible for the final deployment, including serving the application with the correct security headers (COOP/COEP).

If you are researching or developing new parallel runner strategies, you can implement the ParRunner trait.

Existing implementations to use as references:

• adaptive runner (found in src/runner/runner_variants/adaptive_chunk)
• fixed runner (found in src/runner/runner_variants/fixed_chunk)

To test your runner, you can update the DefaultRunner alias and the default_runner() wiring in src/runner/mod.rs on your branch.

A ParRunner is responsible for scheduling decisions, specifically determining how many workers to start and how large each pulled chunk should be. It is decoupled from input ownership, iterator transformations, and the thread pool itself.

Key Responsibilities:

• Scheduling: Deciding worker counts and chunk sizes.
• Lifecycle Management: Responding to thread and chunk lifecycle callbacks.

What it does NOT own:

• ConcurrentIter: Owns concurrent access to input items.
• Xap variants: Own iterator transformations (map, filter, flat_map).
• ThreadPool: Owns scoped execution and worker lifecycle.

To implement a runner, you must satisfy the ParRunner trait, which requires the runner to be Sync because shared runner state is read from worker tasks.

To maintain a synchronous API in Rust while executing work across asynchronous browser workers, orx-parallel uses a Scoped Execution Model.

1. Scope Creation: For every parallel computation, a ScopeRuntime is created, tracking pending tasks and managing synchronization/panics.
2. Task Scheduling: When run(...) is called, the task is either run immediately (if inline_only is true) or boxed as a Task and pushed to a queue.
3. Worker Execution: Workers pop tasks from the queue, execute them using catch_unwind, and record any panics.
4. Synchronization: The main thread waits until the pending task count reaches zero before clearing the scope and resuming any captured panics.

This allows standard parallel iterator calls to work seamlessly in the browser as long as the runtime has been initialized.

To perform performance checks for new or experimental runners, use the orx-parallel-benchmarks repository. Benchmarks run in separate processes to prevent interference from persistent thread pools.

Recommended Workflow:

1. Create a branch in orx-parallel containing your experimental runner.
2. (Optional) Set the runner as the default in src/runner/mod.rs on your branch.
3. In the orx-parallel-benchmarks repository, update the relevant Cargo.toml files to point to your specific branch or local path.
4. Execute benchmarks across several workload categories to ensure broad compatibility.
5. Compare results against built-in runners and Rayon (if a Rayon variant exists).

Workload categories to test:

• Uniform CPU-heavy map/reduce
• Heterogeneous work
• Memory-bound map/filter/collect
• Early-exit search
• Fallible option/result flows
• Recursive traversal

In performance-critical parallel applications, avoid 'immutable' designs that allocate new objects for every iteration (e.g., creating a new Vec inside a .map() call). This leads to $O(N)$ space complexity where $N$ is the number of iterations.

Instead, use use_vec or use_new to manage thread-local buffers. By reusing a fixed set of buffers (one per thread), you reduce space complexity to $O(T)$ where $T$ is the number of threads, significantly reducing allocation pressure and improving cache locality.

You can parallelize standard Rust iterators by substituting sequential methods with parallel equivalents. For common collections, use .par() to convert an iterator to a parallel one. This allows you to use the same functional API (like .map(), .filter(), .min_by_key()) while executing the pipeline in parallel.

Common substitutions:

• iter() -> par()
• into_iter() -> into_par()
• iter_mut() -> par_mut()

use orx_parallel::*;

let best_tour = (0..num_tours)
    .par() // ← parallelized
    .map(|_| Tour::random(num_cities))
    .filter(|t| t.starts_at_coffee_shop())
    .min_by_key(|t| t.duration());