# `state`   [![ci.svg]][ci] [![crates.io]][crate] [![docs.rs]][docs]

[crates.io]: https://img.shields.io/crates/v/state.svg
[crate]: https://crates.io/crates/state
[docs.rs]: https://docs.rs/state/badge.svg
[docs]: https://docs.rs/state
[ci.svg]: https://github.com/SergioBenitez/state/workflows/CI/badge.svg
[ci]: https://github.com/SergioBenitez/state/actions

A Rust library for safe and effortless global and thread-local state management.

```rust
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](https://docs.rs/state) for more.

## Usage

Include `state` in your `Cargo.toml` `[dependencies]`:

```toml
[dependencies]
state = "0.6.0"
```

Thread-local state management is not enabled by default. You can enable it
via the `tls` feature:

```toml
[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](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)