Struct SharedLocalState

Source

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

Expand description

Facilitates sharing of some local state with other threads.

§Examples

Maintain a counter of concurrent threads:

use shared_local_state::SharedLocalState;

let sls = SharedLocalState::new(());
assert_eq!(sls.len(), 1);

// adds a new shared state, causing the count to grow to 2
let sls_2 = sls.insert(());

// signal 1
let (tx1, rx1) = std::sync::mpsc::channel::<()>();
// signal 2
let (tx2, rx2) = std::sync::mpsc::channel::<()>();

std::thread::spawn(move || {
    // perform some work with the shared state in another thread
    sls_2.update_and_notify(|state| assert_eq!(*state, ()));

    // wait for signal 1 which lets us clean up
    for _ in rx1 {}

    // remove shared state, causing the number of shared
    // states to drop back to 1.
    drop(sls_2);

    // send signal 2, telling the main thread that we have
    // cleaned up our shared local state.
    drop(tx2);
});

assert_eq!(sls.len(), 2);

// send signal 1, telling the spawned thread they can clean up
drop(tx1);

// wait for signal 2, when we know the spawned thread has cleaned up
for _ in rx2 {}

assert_eq!(sls.len(), 1);

Implementations§

Source §

impl<T> SharedLocalState<T>

Source

pub fn new(state: T) -> SharedLocalState<T>

Create a new shared registry that makes the provided local state visible to other SharedLocalState handles created through the insert method.

If the returned SharedLocalState object is dropped, the shared state will be removed from the shared registry and dropped as well.

Source

pub fn insert(&self, state: T) -> SharedLocalState<T>

Registers some local state for the rest of the SharedLocalState handles to access.

If the returned SharedLocalState object is dropped, the shared state will be removed from the shared registry and dropped.

Source

pub fn len(&self) -> usize

The number of shared states associated with this SharedLocalState. This will always be non-zero because the existence of a single SharedLocalState implies the existence of at least one shared state.

Source

pub fn update_and_notify<F, R>(&self, f: F) -> R
where F: Fn(&T) -> R,

Update the local shared state and notify any other threads that may be waiting on updates via the find_or_wait method. Only makes sense if T is Sync because it must be accessed through an immutable reference. If you want to minimize the underlying Condvar notification effort, or if you are only interested in viewing the shared local state, use access_without_notification instead.

Source

pub fn access_without_notification<F, R>(&self, f: F) -> R
where F: Fn(&T) -> R,

Accesses the shared local state without notifying other threads that may be waiting for updates in concurrent calls to find_or_wait.

Source

pub fn notify_all(&self)

Ensures that any modifications performed via access_without_notification are visible to threads waiting for updates in concurrent calls to find_or_wait.

Source

pub fn find_or_wait<F, R>(&self, f: F) -> R
where F: Fn(&T) -> Option<R>,

Iterates over all shared states until the provided F returns Some(R), which is then returned from this method. If F does not return Some(R) for any shared state, a condition variable is used to avoid spinning until shared states have been modified.

Source