Crate app_state

Thread-safe, mutable application states for rust.

Examples

Initializing the state

Any app state that may be used must be initialized first. Note: An AppState can not be used as a MutAppState and vice versa. This means that AppState and MutAppState must be initialized separately and use independent values, even if they are of the same type.

use app_state::{AppState, MutAppState, AppStateTrait};

struct MyState {
 counter: u32,
}

fn main() {
  // Initialize the app state
  AppState::init(MyState { counter: 0 });
  // Initialize the mutable app state
  MutAppState::init(MyState { counter: 0 });
}

Using derive

In order to avoid boilerplate code, the InitAppState and InitMutAppState traits can be derived for any struct. These traits provide the init_app_state and init_mut_app_state methods respectively which can be used to initialize the state more easily.

use app_state::{AppState, MutAppState, AppStateTrait, InitAppState, InitMutAppState};

#[derive(Default, InitAppState, InitMutAppState)]
struct MyState {
  counter: u32,
}

fn main() {
  MyState::default().init_app_state();
  MyState::default().init_mut_app_state();
}

Read-only state

App states internally use Arc to allow for thread-safe access.

use app_state::{AppState, AppStateTrait, stateful};

struct MyState {
  counter: u32,
}

#[stateful]
fn func(state: AppState<MyState>) {
  println!("Counter: {}", state.counter);
}

Mutable state

Mutable states internally use a Mutex to ensure thread-safety. This means that when reading from or writing to the state, the mutex must be locked. This can be done either by calling get_mut() or by using the MutAppStateLock type.

use app_state::{MutAppState, AppStateTrait, stateful};

struct MyState {
  counter: u32,
}

#[stateful]
fn func(state: MutAppState<MyState>) {
  let mut state = state.get_mut();
  state.counter += 1;
}

Mutable state (locked)

In order to mutate the state, you must first lock it. This can be done either by calling get_mut() or by using the MutAppStateLock type.

use app_state::{MutAppState, MutAppStateLock, AppStateTrait, stateful};

struct MyState {
  counter: u32,
}

#[stateful]
fn func(mut state: MutAppStateLock<MyState>) {
  state.counter += 1;
}

Get the state manually

You can also get the state manually by calling AppState::get() or MutAppState::get().

use app_state::{AppState, MutAppState, AppStateTrait};

struct MyState {
  counter: u32,
}

fn main() {
  let state = AppState::<MyState>::get();
  let mut_state = MutAppState::<MyState>::get();
}

Structs

AppState

A thread-safe, read-only state container.

MutAppState

A mutable app state.

MutAppStateLock

The lock guard for a mutable app state. This is a wrapper around MutexGuard. When this guard is dropped, the lock will be released. As this locks the state, no other thread can access the state until this guard is dropped.

Traits

AppStateTrait

CreateAppState

InitAppState

InitMutAppState

Attribute Macros

init_default_mut_state

Initialize the default state of the annotated struct on application startup using ctor. The default state is the result of calling Default::default().

init_default_state

Initialize the default state of the annotated struct on application startup using ctor. The default state is the result of calling Default::default().

stateful

Inject app states into the annotated function.

Derive Macros

InitAppState

Derive macro for InitAppState. Allows you to initialize app states with init_app_state.

InitMutAppState

Derive macro for InitMutAppState. Allows you to initialize app states with init_mut_app_state.