app_state/
lib.rs

1//! Thread-safe, mutable application states for rust.
2//!
3//! # Examples
4//! ## Initializing the state
5//! Any app state that may be used must be initialized first.
6//! **Note:** An `AppState` can not be used as a `MutAppState` and vice versa.
7//! This means that `AppState` and `MutAppState` must be initialized separately
8//! and use independent values, even if they are of the same type.
9//!
10//! ```rust
11//! use app_state::{AppState, MutAppState, AppStateTrait};
12//!
13//! struct MyState {
14//!  counter: u32,
15//! }
16//!
17//! fn main() {
18//!   // Initialize the app state
19//!   AppState::init(MyState { counter: 0 });
20//!   // Initialize the mutable app state
21//!   MutAppState::init(MyState { counter: 0 });
22//! }
23//! ```
24//!
25//! ### Using `derive`
26//! In order to avoid boilerplate code, the `InitAppState` and `InitMutAppState`
27//! traits can be derived for any struct. These traits provide the `init_app_state`
28//! and `init_mut_app_state` methods respectively which can be used to initialize
29//! the state more easily.
30//! ```rust
31//! use app_state::{AppState, MutAppState, AppStateTrait, InitAppState, InitMutAppState};
32//!
33//! #[derive(Default, InitAppState, InitMutAppState)]
34//! struct MyState {
35//!   counter: u32,
36//! }
37//!
38//! fn main() {
39//!   MyState::default().init_app_state();
40//!   MyState::default().init_mut_app_state();
41//! }
42//! ```
43//!
44//! ## Read-only state
45//! App states internally use `Arc` to allow for thread-safe access.
46//! ```rust
47//! use app_state::{AppState, AppStateTrait, stateful};
48//!
49//! struct MyState {
50//!   counter: u32,
51//! }
52//!
53//! #[stateful]
54//! fn func(state: AppState<MyState>) {
55//!   println!("Counter: {}", state.counter);
56//! }
57//! ```
58//!
59//! ## Mutable state
60//! Mutable states internally use a `Mutex` to ensure thread-safety.
61//! This means that when reading from or writing to the state, the mutex must be locked.
62//! This can be done either by calling `get_mut()` or by using the `MutAppStateLock` type.
63//! ```rust
64//! use app_state::{MutAppState, AppStateTrait, stateful};
65//!
66//! struct MyState {
67//!   counter: u32,
68//! }
69//!
70//! #[stateful]
71//! fn func(state: MutAppState<MyState>) {
72//!   let mut state = state.get_mut();
73//!   state.counter += 1;
74//! }
75//! ```
76//!
77//! ## Mutable state (locked)
78//! In order to mutate the state, you must first lock it.
79//! This can be done either by calling `get_mut()` or by using the `MutAppStateLock` type.
80//! ```rust
81//! use app_state::{MutAppState, MutAppStateLock, AppStateTrait, stateful};
82//!
83//! struct MyState {
84//!   counter: u32,
85//! }
86//!
87//! #[stateful]
88//! fn func(mut state: MutAppStateLock<MyState>) {
89//!   state.counter += 1;
90//! }
91//! ```
92//!
93//! ## Get the state manually
94//! You can also get the state manually by calling `AppState::get()` or `MutAppState::get()`.
95//! ```no_run
96//! use app_state::{AppState, MutAppState, AppStateTrait};
97//!
98//! struct MyState {
99//!   counter: u32,
100//! }
101//!
102//! fn main() {
103//!   let state = AppState::<MyState>::get();
104//!   let mut_state = MutAppState::<MyState>::get();
105//! }
106//! ```
107
108mod states;
109
110#[cfg(test)]
111mod tests;
112
113pub use crate::states::app_state::*;
114pub use crate::states::mut_app_state_lock::*;
115pub use crate::states::mutable_app_state::*;
116pub use crate::states::traits::*;
117pub use app_state_macros::*;
app_state/lib.rs

app_state/
lib.rs
