pub struct ICoW<ITEM: Debug + Send> { /* private fields */ }Expand description
A main structure which implements CoW approach based on RwLock for the
multithreading syncing. The object stored inside can be read directly, but
modifying the inner value is performed using CoW copy-on-write approach.
The inner value must either Copy, Clone, Default, or provide new value manually. The copied value is modified and stored back either shared or exclusive method. The exclusive lock prevents other CoW operations guaranteeing the uniq write access.
#[derive(Debug, Clone)]
struct TestStruct { s: u32 }
let cow_val = ICoW::new(TestStruct{ s: 2 });
// read
let read0 = cow_val.read().unwrap();
// ...
drop(read0);
// write new non-exclusivly
let mut write0 = cow_val.try_clone().unwrap();
write0.s = 3;
write0.commit().unwrap();
// write new exclusivly
let mut write0 = cow_val.try_clone_exclusivly().unwrap();
write0.s = 3;
write0.commit().unwrap();
Implementations§
Source§impl<ITEM: Debug + Send> ICoW<ITEM>
impl<ITEM: Debug + Send> ICoW<ITEM>
Sourcepub fn get_lock_type() -> ICoWLockTypes
pub fn get_lock_type() -> ICoWLockTypes
Returns the syncing meachanism.
Source§impl<ITEM: Debug + Send> ICoW<ITEM>
impl<ITEM: Debug + Send> ICoW<ITEM>
Sourcepub fn read(&self) -> ICoWRead<'_, ITEM>
pub fn read(&self) -> ICoWRead<'_, ITEM>
Attempts to read the inner value returning the guard. This function blocks the current thread until the value becomes available. This can happen if exclusive copy-on-write is in progress.
§Returns
An instance with clonned reference is returned.
Sourcepub fn try_read(&self) -> Option<ICoWRead<'_, ITEM>>
pub fn try_read(&self) -> Option<ICoWRead<'_, ITEM>>
Attempts to read the inner value, returning the read guard in case of success. This function does not block the current thread until the value becomes available. This function fails if exclusive copy-on-write is in progress.
§Returns
A Option is retrurned. The Option::None is returned if operation would block for a long time.
Sourcepub fn new_exclusivly(&self, new_item: ITEM) -> ICoWLock<'_, ITEM>
pub fn new_exclusivly(&self, new_item: ITEM) -> ICoWLock<'_, ITEM>
Sourcepub fn try_new_exclusivly(
&self,
new_item: ITEM,
) -> Result<ICoWLock<'_, ITEM>, ITEM>
pub fn try_new_exclusivly( &self, new_item: ITEM, ) -> Result<ICoWLock<'_, ITEM>, ITEM>
Attempts to grab the exclusive Copy-on-Write to prevent duplicate writing.
Non-blocking function i.e returns if it fails to acquire the clone before some deadline.
§Returns
An Result is returned where the Option::None is returned if an exclusive CoW lock have already been issued.
Sourcepub fn try_new_inplace(&self, new_item: ITEM) -> Result<(), (ICoWError, ITEM)>
pub fn try_new_inplace(&self, new_item: ITEM) -> Result<(), (ICoWError, ITEM)>
Attempts to update old value to new value for the inner.
Non-blocking function i.e returns if it fails to acquire the clone before some deadline. And does not block if the write access is not available now due to the exclusive lock pending.
Does not return guard. Updates the value in-place.
§Returns
A Result is returned where the Result::Err is returned with:
-
ICoWError::ExclusiveLockPending - if exclsive write already pending.
-
errors which are returned by ICoWCopy::commit().
Sourcepub fn try_new_exclusivly_inplace(
&self,
new_item: ITEM,
) -> Result<(), (ICoWError, ITEM)>
pub fn try_new_exclusivly_inplace( &self, new_item: ITEM, ) -> Result<(), (ICoWError, ITEM)>
Attempts to update old value to new value for the inner exclusively.
Non-blocking function i.e returns if it fails to acquire the clone before some deadline.
Does not return guard. Updates the value in-place.
§Returns
A Result is returned where the Result::Err is returned with:
-
ICoWError::ExclusiveLockPending - if exclsive write already pending.
-
ICoWError::AlreadyUpdated - if duplicate write operation attempt.
-
[ICoWError::RaceCondition] - a race condition detected during update.
-
errors which are returned by ICoWCopy::commit().
Source§impl<ITEM: Debug + Send + Copy> ICoW<ITEM>
impl<ITEM: Debug + Send + Copy> ICoW<ITEM>
Sourcepub fn try_copy(&self) -> Option<ICoWCopy<'_, ITEM>>
pub fn try_copy(&self) -> Option<ICoWCopy<'_, ITEM>>
Attempts to perform the copy of the inner value for writing.
Non-blocking function i.e returns if it fails to acquire the copy before some deadline.
§Returns
An Option is returned where the Option::None is returned if it failed.
Sourcepub fn copy_exclusivly(&self) -> ICoWLock<'_, ITEM>
pub fn copy_exclusivly(&self) -> ICoWLock<'_, ITEM>
Sourcepub fn try_copy_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
pub fn try_copy_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
Attempts to perform the copy of the inner value for exclusive writing.
Non-blocking function i.e returns if it fails to acquire the copy before some deadline.
§Returns
An Option is returned where the Option::None is returned if an exclusive CoW lock have already been issued.
Source§impl<ITEM: Debug + Send + Clone> ICoW<ITEM>
impl<ITEM: Debug + Send + Clone> ICoW<ITEM>
Sourcepub fn try_clone(&self) -> Option<ICoWCopy<'_, ITEM>>
pub fn try_clone(&self) -> Option<ICoWCopy<'_, ITEM>>
Attempts to perform the clone of the inner value for writing.
Non-blocking function i.e returns if it fails to acquire the clone before some deadline.
§Returns
An Option is returned where the Option::None is returned if it failed.
Sourcepub fn clone_exclusivly(&self) -> ICoWLock<'_, ITEM>
pub fn clone_exclusivly(&self) -> ICoWLock<'_, ITEM>
Sourcepub fn try_clone_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
pub fn try_clone_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
Attempts to perform the clone of the inner value for exclusive writing.
Non-blocking function i.e returns if it fails to acquire the clone before some deadline.
§Returns
An Option is returned where the Option::None is returned if an exclusive CoW lock have already been issued.
Source§impl<ITEM: Debug + Send + Default> ICoW<ITEM>
impl<ITEM: Debug + Send + Default> ICoW<ITEM>
Sourcepub fn from_default(&self) -> ICoWCopy<'_, ITEM>
pub fn from_default(&self) -> ICoWCopy<'_, ITEM>
Construct the guard from the Default of the inner value for writing.
Blocking function i.e always retruns the result.
§Returns
An Option is returned where the Option::None is returned if it failed.
Sourcepub fn try_default(&self) -> Option<ICoWCopy<'_, ITEM>>
pub fn try_default(&self) -> Option<ICoWCopy<'_, ITEM>>
Attempts to init default of the inner value for writing.
Non-blocking function i.e returns if it fails to acquire the clone before some deadline.
§Returns
An Option is returned where the Option::None is returned if it failed.
Sourcepub fn default_exclusivly(&self) -> ICoWLock<'_, ITEM>
pub fn default_exclusivly(&self) -> ICoWLock<'_, ITEM>
Forces the exclusive locking the CoW instance and create a default instance after lock is aquired. The lock is holded in the inner of the returned instance.
If other thread is holding the exclusive CoW lock, the current thread will be blocked until lock is released.
§Returns
Always returns ICoWLock.
Sourcepub fn try_default_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
pub fn try_default_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
Attempts to init default of the inner value for exclusive writing.
Non-blocking function i.e returns if it fails to acquire the clone before some deadline.
§Returns
An Option is returned where the Option::None is returned if an exclusive CoW lock have already been issued.