Struct state::Storage

pub struct Storage<T: Send + Sync + 'static> { /* fields omitted */ }

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 + 'static.

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");
}

Methods

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

pub fn new() -> Storage<T>

Create a new, uninitialized storage location.

Example

use state::Storage;

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

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: Fn() -> 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!");

Trait Implementations

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

impl<T: Clone + Send + Sync + 'static> 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: Send + Sync + 'static> From<T> for Storage<T>

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

Performs the conversion.

impl<T: Send + Sync + 'static> Drop for Storage<T>

fn drop(&mut self)

Executes the destructor for this type.

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

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

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

Formats the value using the given formatter.