Struct read_write_store::RwStore [−][src]
pub struct RwStore<Element> { /* fields omitted */ }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
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);Safety
This should not be called more than 232 - 1 times on any given store. When debug assertions are enabled, doing so will panic, but when they are disabled (i.e. in release mode), doing so may cause undefined behavior.
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.
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.
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).
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.
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.
pub fn read_with_timeout(
&self,
id: Id,
timeout: Timeout
) -> BlockResult<Option<ReadLock<'_, Element>>>
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.
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.
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.
pub fn write_with_timeout(
&self,
id: Id,
timeout: Timeout
) -> BlockResult<Option<WriteLock<'_, Element>>>
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.
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.
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.
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());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);Trait Implementations
Creates a consuming iterator that visits each element still present in the store, yielding its ID and value.
The order in which this iterator traverses elements is unspecified.