Struct state::Storage

pub struct Storage<T> { /* private fields */ }

A single storage location for global access to a value.

A Storage instance can hold a single value in a global context. A Storage instance begins without a value and must be initialized via the set method. Once a value has been set, it can be retrieved at any time and in any thread via the get method. The try_get can be used to determine whether the Storage has been initialized before attempting to retrieve the value.

For safety reasons, values stored in Storage must be Send + Sync.

Example

The following example uses Storage to hold a global instance of a HashMap which can be modified at will:

use std::collections::HashMap;
use std::sync::Mutex;
use std::thread;

use state::Storage;

static GLOBAL_MAP: Storage<Mutex<HashMap<String, String>>> = Storage::new();

fn run_program() {
    let mut map = GLOBAL_MAP.get().lock().unwrap();
    map.insert("another_key".into(), "another_value".into());
}

fn main() {
    // Create the initial map and store it in `GLOBAL_MAP`.
    let mut initial_map = HashMap::new();
    initial_map.insert("key".into(), "value".into());
    GLOBAL_MAP.set(Mutex::new(initial_map));

    // For illustration, we spawn a new thread that modified the map.
    thread::spawn(|| run_program()).join().expect("thread");

    // Assert that the modification took place.
    let map = GLOBAL_MAP.get().lock().unwrap();
    assert_eq!(map.get("another_key").unwrap(), "another_value");
}

Implementations

impl<T> Storage<T>

pub const fn new() -> Storage<T>

Create a new, uninitialized storage location.

Example

use state::Storage;

static MY_GLOBAL: Storage<String> = Storage::new();

impl<T: Send + Sync> Storage<T>

pub fn set(&self, value: T) -> bool

Sets the value for this storage unit to value if it has not already been set before.

If a value has previously been set, self is unchanged and false is returned. Otherwise true is returned.

Example

static MY_GLOBAL: Storage<&'static str> = Storage::new();

assert_eq!(MY_GLOBAL.set("Hello, world!"), true);
assert_eq!(MY_GLOBAL.set("Goodbye, world!"), false);

pub fn try_get(&self) -> Option<&T>

Attempts to borrow the value in this storage location.

Returns Some if the state has previously been set. Otherwise returns None.

Example

static MY_GLOBAL: Storage<&'static str> = Storage::new();

assert_eq!(MY_GLOBAL.try_get(), None);

MY_GLOBAL.set("Hello, world!");

assert_eq!(MY_GLOBAL.try_get(), Some(&"Hello, world!"));

pub fn get(&self) -> &T

Borrows the value in this storage location.

Panics

Panics if a value has not previously been set(). Use try_get() for a non-panicking version.

Example

static MY_GLOBAL: Storage<&'static str> = Storage::new();

MY_GLOBAL.set("Hello, world!");
assert_eq!(*MY_GLOBAL.get(), "Hello, world!");

pub fn get_or_set<F: FnOnce() -> T>(&self, from: F) -> &T

If the storage location has not yet been set, it is set to the return value of from. Returns a borrow to the value in this storage location.

Example

static MY_GLOBAL: Storage<&'static str> = Storage::new();

assert_eq!(*MY_GLOBAL.get_or_set(|| "Hello, world!"), "Hello, world!");

pub fn try_get_mut(&mut self) -> Option<&mut T>

Returns a mutable reference to the underlying data if any is set.

This call borrows Storage mutably (at compile-time) so there is no need for dynamic checks.

Example

use state::Storage;

let mut storage = Storage::from(5);
*storage.try_get_mut().unwrap() += 1;

let mut storage: Storage<usize> = Storage::new();
assert!(storage.try_get_mut().is_none());

pub fn into_inner(self) -> Option<T>

Returns the inner value if any is set.

Example

use state::Storage;

let storage = Storage::from(5);
assert_eq!(storage.into_inner().unwrap(), 5);

let storage: Storage<usize> = Storage::new();
assert!(storage.into_inner().is_none());

pub fn map<U: Send + Sync, F: FnOnce(T) -> U>(self, f: F) -> Storage<U>

Applies the function f to the inner value, if there is any, and returns a new Storage with mapped value.

Example

use state::Storage;

let storage = Storage::from(5);
assert_eq!(storage.get(), &5);

let storage = storage.map(|v| v + 10);
assert_eq!(storage.get(), &15);

Trait Implementations

impl<T: Clone + Send + Sync> Clone for Storage<T>

fn clone(&self) -> Storage<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + Send + Sync> Debug for Storage<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Default for Storage<T>

Defaults to Storage::new().

fn default() -> Self

Returns the “default value” for a type.

impl<T: Send + Sync> From<T> for Storage<T>

fn from(value: T) -> Storage<T>

Converts to this type from the input type.

impl<T: Send + Sync> Send for Storage<T>

impl<T: Send + Sync> Sync for Storage<T>