17 releases
0.6.0 | May 25, 2023 |
---|---|
0.5.3 | May 3, 2022 |
0.5.2 | Jun 19, 2021 |
0.4.2 | Oct 28, 2020 |
0.2.0 | Jan 21, 2017 |
#26 in Concurrency
303,903 downloads per month
Used in 639 crates
(29 directly)
74KB
783 lines
state
A Rust library for safe and effortless global and thread-local state management.
extern crate state;
static GLOBAL: state::InitCell<u32> = state::InitCell::new();
GLOBAL.set(42);
assert_eq!(*GLOBAL.get(), 42);
This library can be used to easily implement:
- Lazier Global Statics
- Singletons, Init-Once Values
- Global or Thread-Local Caches, Thunks
- Dynamically-Initialized Thread-Local Data
- Type Maps, Type-Based TypeMaps
See the documentation for more.
Usage
Include state
in your Cargo.toml
[dependencies]
:
[dependencies]
state = "0.6.0"
Thread-local state management is not enabled by default. You can enable it
via the tls
feature:
[dependencies]
state = { version = "0.6.0", features = ["tls"] }
MSRV
The minimum supported Rust version is 1.61.0
as of state
version 0.6
.
Correctness
state
has been extensively vetted, manually and automatically, for soundness
and correctness. All unsafe code, including in internal concurrency
primitives, TypeMap
, and InitCell
are exhaustively verified for pairwise
concurrency correctness and internal aliasing exclusion with loom
.
Multithreading invariants, aliasing invariants, and other soundness properties
are verified with miri
. Verification is run by the CI on every commit.
Performance
state
is heavily tuned to perform optimally. InitCell
is optimal for global
storage retrieval; it is slightly faster than accessing global state
initialized through lazy_static!
, more so across many threads. LocalInitCell
incurs slight overhead due to thread lookup. However, LocalInitCell
has no
synchronization overhead, so retrieval from LocalInitCell
is faster than
through InitCell
across many threads.
Bear in mind that state
allows global initialization at any point in the
program. Other solutions, such as lazy_static!
and thread_local!
allow
initialization only a priori. In other words, state
's abilities are a
superset of those provided by lazy_static!
and thread_local!
while being
more performant.
Testing
Tests can be found in the tests
directory. You can run tests with cargo test --all-features
. Loom verification can be run with RUSTFLAGS="--cfg loom" cargo test --release --test loom
.
License
state
is licensed under either of the following, at your option:
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
Dependencies
~0–27MB
~333K SLoC