Struct RwStore

Source

pub struct RwStore<Element> { /* private fields */ }

Expand description

A concurrent, unordered collection where each element has an internally generated ID and a read-write lock. See the module-level documentation for more.

Implementations§

Source §

impl<Element> RwStore<Element>

Source

pub fn new() -> Self

Creates a new, empty store.

Source

pub fn insert(&self, element: Element) -> Id

Inserts an element into the store, returning it’s generated unique ID. The returned ID can be used to subsequently read, modify or remove the element.

§Example

let store = RwStore::new();
let id = store.insert(42);

Source

pub fn remove(&self, id: Id) -> Option<Element>

Removes an element from the store using its ID if it has not already been removed. Returns the element if it was present.

If a read or write lock is held on the element, this will block until it is released.

§Example

let store = RwStore::new();
let id = store.insert(42);
assert_eq!(store.remove(id), Some(42));

§Safety

The given ID must have been created by this store, see the struct-level documentation.

Source

pub fn remove_with_timeout( &self, id: Id, timeout: Timeout, ) -> BlockResult<Option<Element>>

Removes an element from the store using its ID if it has not already been removed. Returns the element if it was present.

If a read or write lock is held on the element, this will block until it is released or the given timeout expires.

§Example

let store = RwStore::new();
let id = store.insert(42);
let read_lock = store.read(id);
assert!(store.remove_with_timeout(id, DontBlock).is_err());

§Safety

The given ID must have been created by this store, see the struct-level documentation.

Source

pub fn remove_locked(&self, lock: WriteLock<'_, Element>) -> Element

Removes an element from the store directly using a write lock held over the element. This is likely more efficient than unlocking and removing the element, and is guaranteed to succeed atomically, without blocking.

§Example

let store = RwStore::new();
let id = store.insert(42);
let write_lock = store.write(id).unwrap();
assert_eq!(store.remove_locked(write_lock), 42);

§Safety

The given lock must have been acquired from one of the locking methods on this store. Using a lock from another store will panic when debug assertions are enabled, but may cause undefined behavior when they are disabled (i.e. in release mode).

Source

pub fn read(&self, id: Id) -> Option<ReadLock<'_, Element>>

Acquires a read lock on an element given its ID, if it is still present in the store.

If a write lock is held on the element, this will block until it is released.

This may be called reentrantly, but acquiring more than 2³¹ - 2 concurrent read locks on the same element will panic.

§Example

let store = RwStore::new();
let id = store.insert(42);
let read_lock = store.read(id).unwrap();
assert_eq!(*read_lock, 42);

§Safety

The given ID must have been created by this store, see the struct-level documentation.

Source

pub fn read_with_timeout( &self, id: Id, timeout: Timeout, ) -> BlockResult<Option<ReadLock<'_, Element>>>

Acquires a read lock on an element given its ID, if it is still present in the store.

If a write lock is held on the element, this will block until it is released or the given timeout expires.

This may be called reentrantly, but acquiring more than 2³¹ - 2 concurrent read locks on the same element will panic.

§Example

let store = RwStore::new();
let id = store.insert(42);
let write_lock = store.write(id).unwrap();
assert!(store.read_with_timeout(id, DontBlock).is_err());

§Safety

The given ID must have been created by this store, see the struct-level documentation.

Source

pub fn write(&self, id: Id) -> Option<WriteLock<'_, Element>>

Acquires a write lock on an element given its ID, if it is still present in the store.

If a read or write lock is held on the element, this will block until it is released.

§Example

let store = RwStore::new();
let id = store.insert(42);
let mut write_lock = store.write(id).unwrap();
*write_lock = 24;

§Safety

The given ID must have been created by this store, see the struct-level documentation.

Source

pub fn write_with_timeout( &self, id: Id, timeout: Timeout, ) -> BlockResult<Option<WriteLock<'_, Element>>>

Acquires a write lock on an element given its ID, if it is still present in the store.

If a read or write lock is held on the element, this will block until it is released or the given timeout expires.

§Example

let store = RwStore::new();
let id = store.insert(42);
let read_lock = store.read(id).unwrap();
assert!(store.write_with_timeout(id, DontBlock).is_err());

§Safety

The given ID must have been created by this store, see the struct-level documentation.

Source

pub fn get_mut(&mut self, id: Id) -> Option<&mut Element>

Directly obtains a mutable reference to an element given its ID, if it is still present in the store.

Because a mutable reference is held over the store, this can avoid the overhead of locking.

§Example

let mut store = RwStore::new();
let id = store.insert(42);
assert_eq!(store.get_mut(id), Some(&mut 42));

§Safety

The given ID must have been created by this store, see the struct-level documentation.

Source

pub unsafe fn get_mut_unchecked(&mut self, id: Id) -> &mut Element

Directly obtains a mutable reference to an element given its ID, assuming it is still present in the store.

Because a mutable reference is held over the store, this can avoid the overhead of locking.

§Example

let mut store = RwStore::new();
let id = store.insert(42);

unsafe {
    assert_eq!(store.get_mut_unchecked(id), &mut 42);
}

§Safety

If the element whose ID is passed to this method has been removed, then this may cause undefined behavior.

The given ID must have been created by this store, see the struct-level documentation.

Source

pub fn iter_mut(&mut self) -> IterMut<'_, Element> ⓘ

Creates an iterator that visits each element still present in the store, yielding its ID and a mutable reference to it.

The order in which this iterator traverses elements is unspecified.

§Example

let mut store = RwStore::new();
let id = store.insert(42);
let mut iter = store.iter_mut();
assert_eq!(iter.next().unwrap().1, &mut 42);
assert!(iter.next().is_none());

Source

pub fn capacity(&self) -> (u32, u32)

Determines the touched and allocated capacity for this store, and returns them in that order. These should be regarded as hints, if the store is being accessed concurrently the actual capacity values may be larger (but not smaller) than those returned by this method.

The touched capacity is equal to the largest number of elements ever contained in this store at the same time. The allocated capacity is the total number of element slots allocated for use with this store. Neither of these numbers ever decrease.

§Example

let store = RwStore::new();
assert_eq!(store.capacity(), (0, 0));

store.insert(42);
let (touched, allocated) = store.capacity();
assert_eq!(touched, 1);
assert!(allocated >= 1);