execution_context/lib.rs
1//! This crate implements an execution context for Rust. An execution context
2//! carries data through a logical flow of execution.
3//!
4//! This is heavily inspired by the .NET `ExecutionContext` system as an
5//! experiment if such an API would make sense in Rust.
6//!
7//! The main differences to the system in .NET:
8//!
9//! * This purely implements an execution context and not a synchronization
10//! context. As such the implementation is simplified.
11//! * This provides the ability to permanently disable the flow propagation.
12//! * This crate refers to "ambient data" and "async locals" as "flow-local data".
13//! * Capturing always returns an execution context even if the flow is
14//! suppressed. Consequently the run method is no longer static but
15//! stored on the instance.
16//! * This uses atomic reference counting underneath the hood instead of
17//! using a garbage collector. This also means that performance
18//! characteristics will be different.
19//! * `FlowLocal` data have a initialization expression that is invoked if
20//! no local data is stored in the current flow.
21//!
22//! # Example Usage
23//!
24//! ```
25//! #[macro_use]
26//! extern crate execution_context;
27//!
28//! use execution_context::ExecutionContext;
29//! use std::env;
30//! use std::thread;
31//!
32//! flow_local!(static LOCALE: String = env::var("LANG").unwrap_or_else(|_| "en_US".into()));
33//!
34//! fn main() {
35//! println!("the current locale is {}", LOCALE.get());
36//! LOCALE.set("de_DE".into());
37//! println!("changing locale to {}", LOCALE.get());
38//!
39//! let ec = ExecutionContext::capture();
40//! thread::spawn(move || {
41//! ec.run(|| {
42//! println!("the locale in the child thread is {}", LOCALE.get());
43//! LOCALE.set("fr_FR".into());
44//! println!("the new locale in the child thread is {}", LOCALE.get());
45//! });
46//! }).join().unwrap();
47//!
48//! println!("the locale of the parent thread is again {}", LOCALE.get());
49//! }
50//! ```
51//!
52//! This example will give the following output assuming no default language was
53//! set as environment variable (or the environment variable is `en_US`):
54//!
55//! ```plain
56//! the current locale is en_US
57//! changing locale to de_DE
58//! the locale in the child thread is de_DE
59//! the new locale in the child thread is fr_FR
60//! the locale of the parent thread is again de_DE
61//! ```
62extern crate im;
63#[macro_use]
64extern crate lazy_static;
65
66mod ctx;
67mod data;
68
69pub use ctx::*;
70pub use data::*;