Struct MutableSnapshot

pub struct MutableSnapshot<T: Debug>(pub MutableOnDemand<Option<SharedSnapshot<T>>>);

Use this type for fields in structs that are to store the Snapshot, typically behind an OwnShared.

Note that the resource itself is behind another OwnShared to allow it to be used without holding any kind of lock, hence without blocking updates while it is used.

Tuple Fields

0: MutableOnDemand<Option<SharedSnapshot<T>>>

Implementations

impl<T: Debug> MutableSnapshot<T>

pub fn new() -> Self

Create a new instance of this type.

Useful in case Default::default() isn’t working for some reason.

pub fn force_refresh<E>( &self, open: impl FnOnce() -> Result<Option<(SystemTime, T)>, E>, ) -> Result<(), E>

Refresh state forcefully by re-opening the resource. Note that open() returns None if the resource isn’t present on disk, and that it’s critical that the modified time is obtained before opening the resource.

pub fn recent_snapshot<E>( &self, current_modification_time: impl FnMut() -> Option<SystemTime>, open: impl FnOnce() -> Result<Option<T>, E>, ) -> Result<Option<SharedSnapshot<T>>, E>

Assure that the resource in state is up-to-date by comparing the current_modification_time with the one we know in state and by acting accordingly. Returns the potentially updated/reloaded resource if it is still present on disk, which then represents a snapshot that is up-to-date in that very moment, or None if the underlying file doesn’t exist.

Note that even though this is racy, each time a request is made there is a chance to see the actual state.

Methods from Deref<Target = MutableOnDemand<Option<SharedSnapshot<T>>>>

pub unsafe fn make_read_guard_unchecked(&self) -> RwLockReadGuard<'_, R, T>

Available on crate feature parallel only.

Creates a new RwLockReadGuard without checking if the lock is held.

Safety

This method must only be called if the thread logically holds a read lock.

This function does not increment the read count of the lock. Calling this function when a guard has already been produced is undefined behaviour unless the guard was forgotten with mem::forget.

pub unsafe fn make_write_guard_unchecked(&self) -> RwLockWriteGuard<'_, R, T>

Available on crate feature parallel only.

Creates a new RwLockReadGuard without checking if the lock is held.

Safety

This method must only be called if the thread logically holds a write lock.

Calling this function when a guard has already been produced is undefined behaviour unless the guard was forgotten with mem::forget.

pub fn read(&self) -> RwLockReadGuard<'_, R, T>

Available on crate feature parallel only.

Locks this RwLock with shared read access, blocking the current thread until it can be acquired.

The calling thread will be blocked until there are no more writers which hold the lock. There may be other readers currently inside the lock when this method returns.

Note that attempts to recursively acquire a read lock on a RwLock when the current thread already holds one may result in a deadlock.

Returns an RAII guard which will release this thread’s shared access once it is dropped.

pub fn try_read(&self) -> Option<RwLockReadGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with shared read access.

If the access could not be granted at this time, then None is returned. Otherwise, an RAII guard is returned which will release the shared access when it is dropped.

This function does not block.

pub fn write(&self) -> RwLockWriteGuard<'_, R, T>

Available on crate feature parallel only.

Locks this RwLock with exclusive write access, blocking the current thread until it can be acquired.

This function will not return while other writers or other readers currently have access to the lock.

Returns an RAII guard which will drop the write access of this RwLock when dropped.

pub fn try_write(&self) -> Option<RwLockWriteGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to lock this RwLock with exclusive write access.

If the lock could not be acquired at this time, then None is returned. Otherwise, an RAII guard is returned which will release the lock when it is dropped.

This function does not block.

pub fn is_locked(&self) -> bool

Available on crate feature parallel only.

Checks whether this RwLock is currently locked in any way.

pub fn is_locked_exclusive(&self) -> bool

Available on crate feature parallel only.

Check if this RwLock is currently exclusively locked.

pub unsafe fn force_unlock_read(&self)

Available on crate feature parallel only.

Forcibly unlocks a read lock.

This is useful when combined with mem::forget to hold a lock without the need to maintain a RwLockReadGuard object alive, for example when dealing with FFI.

Safety

This method must only be called if the current thread logically owns a RwLockReadGuard but that guard has be discarded using mem::forget. Behavior is undefined if a rwlock is read-unlocked when not read-locked.

pub unsafe fn force_unlock_write(&self)

Available on crate feature parallel only.

Forcibly unlocks a write lock.

This is useful when combined with mem::forget to hold a lock without the need to maintain a RwLockWriteGuard object alive, for example when dealing with FFI.

Safety

This method must only be called if the current thread logically owns a RwLockWriteGuard but that guard has be discarded using mem::forget. Behavior is undefined if a rwlock is write-unlocked when not write-locked.

pub unsafe fn raw(&self) -> &R

Available on crate feature parallel only.

Returns the underlying raw reader-writer lock object.

Note that you will most likely need to import the RawRwLock trait from lock_api to be able to call functions on the raw reader-writer lock.

Safety

This method is unsafe because it allows unlocking a mutex while still holding a reference to a lock guard.

pub fn data_ptr(&self) -> *mut T

Available on crate feature parallel only.

Returns a raw pointer to the underlying data.

This is useful when combined with mem::forget to hold a lock without the need to maintain a RwLockReadGuard or RwLockWriteGuard object alive, for example when dealing with FFI.

Safety

You must ensure that there are no data races when dereferencing the returned pointer, for example if the current thread logically owns a RwLockReadGuard or RwLockWriteGuard but that guard has been discarded using mem::forget.

pub unsafe fn force_unlock_read_fair(&self)

Available on crate feature parallel only.

Forcibly unlocks a read lock using a fair unlock protocol.

This is useful when combined with mem::forget to hold a lock without the need to maintain a RwLockReadGuard object alive, for example when dealing with FFI.

Safety

This method must only be called if the current thread logically owns a RwLockReadGuard but that guard has be discarded using mem::forget. Behavior is undefined if a rwlock is read-unlocked when not read-locked.

pub unsafe fn force_unlock_write_fair(&self)

Available on crate feature parallel only.

Forcibly unlocks a write lock using a fair unlock protocol.

This is useful when combined with mem::forget to hold a lock without the need to maintain a RwLockWriteGuard object alive, for example when dealing with FFI.

Safety

This method must only be called if the current thread logically owns a RwLockWriteGuard but that guard has be discarded using mem::forget. Behavior is undefined if a rwlock is write-unlocked when not write-locked.

pub fn try_read_for( &self, timeout: <R as RawRwLockTimed>::Duration, ) -> Option<RwLockReadGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with shared read access until a timeout is reached.

If the access could not be granted before the timeout expires, then None is returned. Otherwise, an RAII guard is returned which will release the shared access when it is dropped.

pub fn try_read_until( &self, timeout: <R as RawRwLockTimed>::Instant, ) -> Option<RwLockReadGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with shared read access until a timeout is reached.

If the access could not be granted before the timeout expires, then None is returned. Otherwise, an RAII guard is returned which will release the shared access when it is dropped.

pub fn try_write_for( &self, timeout: <R as RawRwLockTimed>::Duration, ) -> Option<RwLockWriteGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with exclusive write access until a timeout is reached.

If the access could not be granted before the timeout expires, then None is returned. Otherwise, an RAII guard is returned which will release the exclusive access when it is dropped.

pub fn try_write_until( &self, timeout: <R as RawRwLockTimed>::Instant, ) -> Option<RwLockWriteGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with exclusive write access until a timeout is reached.

If the access could not be granted before the timeout expires, then None is returned. Otherwise, an RAII guard is returned which will release the exclusive access when it is dropped.

pub fn read_recursive(&self) -> RwLockReadGuard<'_, R, T>

Available on crate feature parallel only.

Locks this RwLock with shared read access, blocking the current thread until it can be acquired.

The calling thread will be blocked until there are no more writers which hold the lock. There may be other readers currently inside the lock when this method returns.

Unlike read, this method is guaranteed to succeed without blocking if another read lock is held at the time of the call. This allows a thread to recursively lock a RwLock. However using this method can cause writers to starve since readers no longer block if a writer is waiting for the lock.

Returns an RAII guard which will release this thread’s shared access once it is dropped.

pub fn try_read_recursive(&self) -> Option<RwLockReadGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with shared read access.

If the access could not be granted at this time, then None is returned. Otherwise, an RAII guard is returned which will release the shared access when it is dropped.

This method is guaranteed to succeed if another read lock is held at the time of the call. See the documentation for read_recursive for details.

This function does not block.

pub fn try_read_recursive_for( &self, timeout: <R as RawRwLockTimed>::Duration, ) -> Option<RwLockReadGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with shared read access until a timeout is reached.

If the access could not be granted before the timeout expires, then None is returned. Otherwise, an RAII guard is returned which will release the shared access when it is dropped.

This method is guaranteed to succeed without blocking if another read lock is held at the time of the call. See the documentation for read_recursive for details.

pub fn try_read_recursive_until( &self, timeout: <R as RawRwLockTimed>::Instant, ) -> Option<RwLockReadGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with shared read access until a timeout is reached.

If the access could not be granted before the timeout expires, then None is returned. Otherwise, an RAII guard is returned which will release the shared access when it is dropped.

pub unsafe fn make_upgradable_guard_unchecked( &self, ) -> RwLockUpgradableReadGuard<'_, R, T>

Available on crate feature parallel only.

Creates a new RwLockUpgradableReadGuard without checking if the lock is held.

Safety

This method must only be called if the thread logically holds an upgradable read lock.

This function does not increment the read count of the lock. Calling this function when a guard has already been produced is undefined behaviour unless the guard was forgotten with mem::forget.

pub fn upgradable_read(&self) -> RwLockUpgradableReadGuard<'_, R, T>

Available on crate feature parallel only.

Locks this RwLock with upgradable read access, blocking the current thread until it can be acquired.

The calling thread will be blocked until there are no more writers or other upgradable reads which hold the lock. There may be other readers currently inside the lock when this method returns.

Returns an RAII guard which will release this thread’s shared access once it is dropped.

pub fn try_upgradable_read(&self) -> Option<RwLockUpgradableReadGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with upgradable read access.

If the access could not be granted at this time, then None is returned. Otherwise, an RAII guard is returned which will release the shared access when it is dropped.

This function does not block.

pub fn try_upgradable_read_for( &self, timeout: <R as RawRwLockTimed>::Duration, ) -> Option<RwLockUpgradableReadGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with upgradable read access until a timeout is reached.

If the access could not be granted before the timeout expires, then None is returned. Otherwise, an RAII guard is returned which will release the shared access when it is dropped.

pub fn try_upgradable_read_until( &self, timeout: <R as RawRwLockTimed>::Instant, ) -> Option<RwLockUpgradableReadGuard<'_, R, T>>

Available on crate feature parallel only.

Attempts to acquire this RwLock with upgradable read access until a timeout is reached.

If the access could not be granted before the timeout expires, then None is returned. Otherwise, an RAII guard is returned which will release the shared access when it is dropped.

Trait Implementations

impl<T: Debug + Debug> Debug for MutableSnapshot<T>

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

Formats the value using the given formatter.

impl<T: Default + Debug> Default for MutableSnapshot<T>

fn default() -> MutableSnapshot<T>

Returns the “default value” for a type.

impl<T: Debug> Deref for MutableSnapshot<T>

type Target = RwLock<RawRwLock, Option<Arc<Snapshot<T>>>>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.