pub struct ICoW<ITEM: Sized>(/* private fields */);Expand description
A main structure which implements CoW approach based on RwLock. The object
stored inside can be read directly, but modifying the inner value is
performed using CoW copy-on-write approach.
The read operations are faster than write, because in order to write a
more operations needs to be performed.
This is for Mutlithreading environment only. It will be usedless when using
in single-thread programs. For the single thread, use a SICoW which would
improve the performance.
The inner value must be 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_copy().unwrap();
write0.s = 3;
write0.commit().unwrap();
// write new exclusivly
let mut write0 = cow_val.try_clone_copy_exclusivly().unwrap();
write0.s = 3;
write0.commit().unwrap();
Implementations§
Source§impl<ITEM> ICoW<ITEM>
impl<ITEM> ICoW<ITEM>
Sourcepub fn reader(&self) -> ICoWWeak<ITEM>
pub fn reader(&self) -> ICoWWeak<ITEM>
Reads the inner value returning the weak reader which allows
to keep it somewhere else i.e in the thread_local. The returned
item is not Sync but can be sent to other thread Send.
If the base ICoW will be dropped, the instance should instantly
become no longer valid which means that it won’t be possible to
aquire read.
§Returns
An instance with Weak references to ITEM and ICoW.
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 guard. 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 is in progress.
-
ICoWError::WouldBlock - if failed to acquire lock in reasonable time.
-
errors which are returned by ICoWCopy::commit().
Source§impl<ITEM: Debug + Copy> ICoW<ITEM>
impl<ITEM: Debug + 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 copy_exclusive_or_read(
&self,
) -> Result<ICoWLock<'_, ITEM>, ICoWRead<'_, ITEM>>
pub fn copy_exclusive_or_read( &self, ) -> Result<ICoWLock<'_, ITEM>, ICoWRead<'_, 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 + Clone> ICoW<ITEM>
impl<ITEM: Debug + Clone> ICoW<ITEM>
Sourcepub fn clone_copy(&self) -> ICoWCopy<'_, ITEM>
pub fn clone_copy(&self) -> ICoWCopy<'_, ITEM>
Sourcepub fn try_clone_copy(&self) -> Option<ICoWCopy<'_, ITEM>>
pub fn try_clone_copy(&self) -> Option<ICoWCopy<'_, ITEM>>
[!IMPORTANT] Previously
try_clone(). renamed totry_clone_copy()due to the conflict with Clone.
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_copy_exclus_or_read(
&self,
) -> Result<ICoWLock<'_, ITEM>, ICoWRead<'_, ITEM>>
pub fn clone_copy_exclus_or_read( &self, ) -> Result<ICoWLock<'_, ITEM>, ICoWRead<'_, ITEM>>
Sourcepub fn clone_copy_exclusivly(&self) -> ICoWLock<'_, ITEM>
pub fn clone_copy_exclusivly(&self) -> ICoWLock<'_, ITEM>
[!IMPORTANT] Previously
clone_exclusivly(). renamed toclone_copy_exclusivly()due to the conflict with Clone.
Forces the exclusive locking the CoW instance and cloning the content 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_clone_copy_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
pub fn try_clone_copy_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
[!IMPORTANT] Previously
try_clone_exclusivly(). renamed totry_clone_copy_exclusivly()due to the conflict with Clone.
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 + Default> ICoW<ITEM>
impl<ITEM: Debug + 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.