libpetri_runtime/lib.rs
1//! # libpetri-runtime — Petri Net Executors
2//!
3//! Provides two executors for running Coloured Time Petri Nets defined with
4//! [`libpetri-core`](https://docs.rs/libpetri-core).
5//!
6//! ## BitmapNetExecutor
7//!
8//! The general-purpose executor. Single-threaded orchestrator with concurrent
9//! async actions.
10//!
11#![doc = include_str!(concat!(env!("OUT_DIR"), "/executor_example.svg"))]
12//!
13//! ### Execution Loop (5 phases per cycle)
14//!
15//! 1. **Process completed** — collect outputs from finished async actions
16//! 2. **Process events** — inject tokens from environment places
17//! 3. **Update dirty** — re-evaluate enablement via bitmap masks (O(W) where W = ceil(places/64))
18//! 4. **Fire ready** — sorted by priority, then FIFO by enablement time
19//! 5. **Await work** — sleep until action completes, timer fires, or event arrives
20//!
21//! ### Key types
22//!
23//! - [`BitmapNetExecutor`](executor::BitmapNetExecutor) — the executor
24//! - [`CompiledNet`](compiled_net::CompiledNet) — precomputed bitmap masks and reverse indexes
25//! - [`ExecutorOptions`](executor::ExecutorOptions) — configuration (e.g. time source override)
26//!
27//! ## PrecompiledNetExecutor
28//!
29//! A high-performance alternative optimized for throughput-critical workloads.
30//!
31#![doc = include_str!(concat!(env!("OUT_DIR"), "/precompiled_example.svg"))]
32//!
33//! Additional optimizations over BitmapNetExecutor:
34//! - Ring buffer token storage (flat `Vec<Option<ErasedToken>>` pool)
35//! - Opcode-based consume dispatch (CONSUME_ONE, CONSUME_N, CONSUME_ALL, RESET)
36//! - Two-level summary bitmaps for dirty/enabled iteration
37//! - Reusable `HashMap` buffers reclaimed via `take_inputs()`/`take_reads()`
38//! - Priority-partitioned ready queues
39//!
40//! ### Key types
41//!
42//! - [`PrecompiledNetExecutor`](precompiled_executor::PrecompiledNetExecutor) — the executor
43//! - [`PrecompiledNet`](precompiled_net::PrecompiledNet) — borrows `&CompiledNet`, zero-cost reuse
44//!
45//! ## Compilation Pipeline
46//!
47//! ```text
48//! PetriNet ──► CompiledNet ──► PrecompiledNet (optional)
49//! (bitmap masks) (ring buffers, opcodes)
50//! ```
51//!
52//! ## Marking
53//!
54//! [`Marking`](marking::Marking) holds the mutable token state — type-erased
55//! FIFO queues per place, with typed access via `Place<T>` references.
56//!
57//! ## Async Support
58//!
59//! Enable the `tokio` feature for `run_async()` on both executors. This allows
60//! transition actions to be async (`CompletableFuture`-style) with external
61//! event injection via environment places.
62
63pub mod bitmap;
64pub mod compiled_net;
65pub mod environment;
66pub mod executor;
67pub mod marking;
68pub mod precompiled_executor;
69pub mod precompiled_net;