simvar/lib.rs
1//! Deterministic simulation test harness for concurrent systems.
2//!
3//! This crate is a facade that re-exports the core simulation testing framework from
4//! [`simvar_harness`] and optional utilities from [`simvar_utils`]. It provides a unified
5//! interface for writing deterministic tests of distributed systems and concurrent applications.
6//!
7//! # Features
8//!
9//! * **Deterministic execution** - Same seed produces identical simulation results
10//! * **Host and client actors** - Model persistent services (hosts) and ephemeral clients
11//! * **Simulation lifecycle hooks** - Customize behavior at key points via [`SimBootstrap`]
12//! * **Built-in TUI** - Optional terminal UI for monitoring simulation progress (with `tui` feature)
13//! * **Parallel execution** - Run multiple simulation runs concurrently
14//! * **Cancellation support** - Graceful shutdown with Ctrl-C handling
15//!
16//! # Example
17//!
18//! ```rust,no_run
19//! use simvar::{run_simulation, SimBootstrap, Sim, SimConfig};
20//!
21//! struct MyBootstrap;
22//!
23//! impl SimBootstrap for MyBootstrap {
24//! fn build_sim(&self, config: SimConfig) -> SimConfig {
25//! config
26//! }
27//!
28//! fn on_start(&self, sim: &mut impl Sim) {
29//! // Spawn a host actor
30//! sim.host("server", || async {
31//! // Server logic here
32//! Ok(())
33//! });
34//!
35//! // Spawn a client actor
36//! sim.client("client", async {
37//! // Client logic here
38//! Ok(())
39//! });
40//! }
41//! }
42//!
43//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
44//! let results = run_simulation(MyBootstrap)?;
45//! # Ok(())
46//! # }
47//! ```
48//!
49//! # Feature Flags
50//!
51//! * `all` (default) - Enable all features
52//! * `async` - Async runtime support
53//! * `database` - Database simulation
54//! * `fs` - Filesystem simulation
55//! * `http` - HTTP client/server simulation
56//! * `mdns` - mDNS simulation
57//! * `random` - Random number generation simulation
58//! * `tcp` - TCP connection simulation
59//! * `telemetry` - Telemetry support
60//! * `time` - Time simulation
61//! * `tui` - Terminal UI for simulation visualization
62//! * `upnp` - `UPnP` simulation
63//! * `utils` - Simulation utilities module
64//! * `web-server` - Web server simulation
65//! * `pretty_env_logger` - Pretty logging output
66//!
67//! # Environment Variables
68//!
69//! * `SIMULATOR_RUNS` - Number of simulation runs to execute (default: 1)
70//! * `SIMULATOR_MAX_PARALLEL` - Maximum parallel runs (default: number of CPUs)
71//! * `NO_TUI` - Disable terminal UI when set
72
73#![cfg_attr(feature = "fail-on-warnings", deny(warnings))]
74#![warn(clippy::all, clippy::pedantic, clippy::nursery, clippy::cargo)]
75#![allow(clippy::multiple_crate_versions)]
76
77/// Simulation utilities module.
78///
79/// Provides utility functions for managing worker threads and cancellation tokens
80/// in simulation environments. Includes thread-local and global cancellation support
81/// for gracefully terminating simulations and async operations.
82///
83/// Requires the `utils` feature flag.
84#[cfg(feature = "utils")]
85pub use simvar_utils as utils;
86
87/// Core simulation harness APIs.
88///
89/// Re-exports all public types, traits, and functions from [`simvar_harness`],
90/// including [`run_simulation`], [`Sim`], [`SimBootstrap`], and [`SimConfig`].
91pub use simvar_harness::*;