desque/
lib.rs

1//! # Overview
2//!
3//! desque is a lightweight framework for developing discrete-event simulations, depending only on the Rust standard
4//! library by default. While desque provides little more than an event queue and a runner, both constructs make use of
5//! generic templating to provide you with control over how a desque simulation operates:
6//!
7//! * The [`Event`] trait guarantees exclusive access to the simulation's state at runtime, without forcing you to
8//!   choose between interior mutability or unsafe access to mutable, static data.
9//! * Parameterizing over the [`SimState`] trait gives full access to your use case's implementing type while executing
10//!   events, with no requirements placed on that type.
11//! * The [`Simulation`] struct expects each event to be capable of failing, gracefully halting execution if an event
12//!   returns an error to give client code the option of handling it outside the event loop.
13//! * Parameterizing over the [`SimTime`] trait gives full control over how events are sequenced at runtime, determined
14//!   entirely through your type's implementation of the [`Ord`] supertrait.
15//!
16//! The expectation in desque that a [`Simulation`] own all data associated with a replication also supports the
17//! application of variance-reduction techniques from the statistical field known as design of experiments. For example,
18//! a desque simulation can use the antithetic variates technique by creating paired random-number generators and
19//! handing each generator (along with copies of initializing data) to a different thread. As desque provides each
20//! executing event exclusive access to simulation state, it is straightforward for simulation developers to ensure that
21//! replications on separate threads are isolated from each other, shielding them from unplanned dependencies which may
22//! affect statistical results.
23//!
24//! # Features
25//!
26//! desque offers one feature, `ordered-float`, which provides the option to add a dependency on the [`ordered-float`]
27//! crate so that its [`OrderedFloat`] and [`NotNan`] structs may be used as [`SimTime`]. Its `std` feature will be
28//! enabled, as desque requires access to the standard library anyway, but no other features of [`ordered-float`] are
29//! enforced - add them in your Cargo.toml if you need them. By default, this feature is disabled in desque to avoid a
30//! potentially unnecessary dependency.
31//!
32//! [`ordered-float`]: https://docs.rs/ordered-float/4
33//! [`OrderedFloat`]: https://docs.rs/ordered-float/4/ordered_float/struct.OrderedFloat.html
34//! [`NotNan`]: https://docs.rs/ordered-float/4/ordered_float/struct.NotNan.html
35//! [`Simulation`]: serial::Simulation
36//! [`Event`]: serial::Event
37
38mod error;
39mod generic_parameters;
40pub mod serial;
41pub mod threadsafe;
42
43pub use error::{Error, Result};
44pub use generic_parameters::{SimState, SimTime};
desque/lib.rs

desque/
lib.rs
