pub struct Storage<T> { /* private fields */ }
Expand description
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
sourceimpl<T: Send + Sync> Storage<T>
impl<T: Send + Sync> Storage<T>
sourcepub fn set(&self, value: T) -> bool
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);
sourcepub fn try_get(&self) -> Option<&T>
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!"));
sourcepub fn get_or_set<F: FnOnce() -> T>(&self, from: F) -> &T
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!");
sourcepub fn try_get_mut(&mut self) -> Option<&mut T>
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());
sourcepub fn into_inner(self) -> Option<T>
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());
sourcepub fn map<U: Send + Sync, F: FnOnce(T) -> U>(self, f: F) -> Storage<U>
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
sourceimpl<T> Default for Storage<T>
impl<T> Default for Storage<T>
Defaults to Storage::new()
.
impl<T: Send + Sync> Send for Storage<T>
impl<T: Send + Sync> Sync for Storage<T>
Auto Trait Implementations
impl<T> !RefUnwindSafe for Storage<T>
impl<T> Unpin for Storage<T> where
T: Unpin,
impl<T> UnwindSafe for Storage<T> where
T: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more