Struct lunatic::ProcessLocal

pub struct ProcessLocal<T: 'static> { /* private fields */ }

A process local storage which owns its contents.

It is instantiated with the process_local! macro and the primary method is the with method.

The with method yields a reference to the contained value which cannot escape the given closure.

Initialization and Destruction

Initialization is dynamically performed on the first call to with within a process, and values are never destructed. This means if a process finishes normally or panics, the Drop implementation will never ba called.

A ProcessLocal’s initializer cannot recursively depend on itself, and using a ProcessLocal in this way will cause the initializer to infinitely recurse on the first call to with.

Examples

use lunatic::{process_local, spawn_link};
use std::cell::RefCell;

process_local!(static FOO: RefCell<u32> = RefCell::new(1));

FOO.with(|f| {
    assert_eq!(*f.borrow(), 1);
    *f.borrow_mut() = 2;
});

// each process starts out with the initial value of 1
let child = spawn_link!(@task || {
    FOO.with(|f| {
        assert_eq!(*f.borrow(), 1);
        *f.borrow_mut() = 3;
    });
});

// wait for the process to complete
let _ = child.result();

// we retain our original value of 2 despite the child process
FOO.with(|f| {
    assert_eq!(*f.borrow(), 2);
});

Implementations

impl<T: 'static> ProcessLocal<T>

pub fn with<F, R>(&'static self, f: F) -> R where
    F: FnOnce(&'static T) -> R, 

Acquires a reference to the value in this process local.

This will lazily initialize the value if this process has not referenced it yet.

impl<T: 'static> ProcessLocal<Cell<T>>

pub fn set(&'static self, value: T)

Sets or initializes the contained value.

Unlike the other methods, this will not run the lazy initializer of the process local. Instead, it will be directly initialized with the given value if it wasn’t initialized yet.

Examples

use std::cell::Cell;

process_local! {
    static X: Cell<i32> = panic!("!");
}

// Calling X.get() here would result in a panic.

X.set(123); // But X.set() is fine, as it skips the initializer above.

assert_eq!(X.get(), 123);

pub fn get(&'static self) -> T where
    T: Copy, 

Returns a copy of the contained value.

This will lazily initialize the value if this process has not referenced it yet.

Examples

use std::cell::Cell;

process_local! {
    static X: Cell<i32> = Cell::new(1);
}

assert_eq!(X.get(), 1);

pub fn take(&'static self) -> T where
    T: Default, 

Takes the contained value, leaving Default::default() in its place.

This will lazily initialize the value if this process has not referenced it yet.

Examples

use std::cell::Cell;

process_local! {
    static X: Cell<Option<i32>> = Cell::new(Some(1));
}

assert_eq!(X.take(), Some(1));
assert_eq!(X.take(), None);

pub fn replace(&'static self, value: T) -> T

Replaces the contained value, returning the old value.

This will lazily initialize the value if this process has not referenced it yet.

Examples

use std::cell::Cell;

process_local! {
    static X: Cell<i32> = Cell::new(1);
}

assert_eq!(X.replace(2), 1);
assert_eq!(X.replace(3), 2);

impl<T: 'static> ProcessLocal<RefCell<T>>

pub fn with_borrow<F, R>(&'static self, f: F) -> R where
    F: FnOnce(Ref<'static, T>) -> R, 

Acquires a reference to the contained value.

This will lazily initialize the value if this process has not referenced it yet.

Panics

Panics if the value is currently mutably borrowed.

Example

use std::cell::RefCell;

process_local! {
    static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
}

X.with_borrow(|v| assert!(v.is_empty()));

pub fn with_borrow_mut<F, R>(&'static self, f: F) -> R where
    F: FnOnce(RefMut<'static, T>) -> R, 

Acquires a mutable reference to the contained value.

This will lazily initialize the value if this process has not referenced it yet.

Panics

Panics if the value is currently borrowed.

Example

use std::cell::RefCell;

process_local! {
    static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
}

X.with_borrow_mut(|v| v.push(1));

X.with_borrow(|v| assert_eq!(*v, vec![1]));

pub fn set(&'static self, value: T)

Sets or initializes the contained value.

Unlike the other methods, this will not run the lazy initializer of the process local. Instead, it will be directly initialized with the given value if it wasn’t initialized yet.

Panics

Panics if the value is currently borrowed.

Examples

use std::cell::RefCell;

process_local! {
    static X: RefCell<Vec<i32>> = panic!("!");
}

// Calling X.with() here would result in a panic.

X.set(vec![1, 2, 3]); // But X.set() is fine, as it skips the initializer above.

X.with_borrow(|v| assert_eq!(*v, vec![1, 2, 3]));

pub fn take(&'static self) -> T where
    T: Default, 

Takes the contained value, leaving Default::default() in its place.

This will lazily initialize the value if this process has not referenced it yet.

Panics

Panics if the value is currently borrowed.

Examples

use std::cell::RefCell;

process_local! {
    static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
}

X.with_borrow_mut(|v| v.push(1));

let a = X.take();

assert_eq!(a, vec![1]);

X.with_borrow(|v| assert!(v.is_empty()));

pub fn replace(&'static self, value: T) -> T

Replaces the contained value, returning the old value.

Panics

Panics if the value is currently borrowed.

Examples

use std::cell::RefCell;

process_local! {
    static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
}

let prev = X.replace(vec![1, 2, 3]);
assert!(prev.is_empty());

X.with_borrow(|v| assert_eq!(*v, vec![1, 2, 3]));

Trait Implementations

impl<T: 'static> Debug for ProcessLocal<T>

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

Formats the value using the given formatter.