Struct Synchronizer 

pub struct Synchronizer<H: Hasher + Default = WyHash, WL = LockDisabled, const N: usize = 1024, const SD: u64 = 1000000000> { /* private fields */ }

Synchronizer is a concurrency primitive that manages data access between a single writer process and multiple reader processes.

It coordinates the access to two data files that store the shared data. A state file, also memory-mapped, stores the index of the current data file and the number of active readers for each index, updated via atomic instructions.

Template parameters:

• H - hasher used for checksum calculation
• WL - optional write locking to prevent multiple writers. (default LockDisabled)
• N - serializer scratch space size
• SD - sleep duration in nanoseconds used by writer during lock acquisition (default 1s)

Implementations

impl Synchronizer

pub fn new(path_prefix: &OsStr) -> Self

Create new instance of Synchronizer using given path_prefix and default template parameters

impl<'a, H, WL, const N: usize, const SD: u64> Synchronizer<H, WL, N, SD>

where H: Hasher + Default, WL: WriteLockStrategy<'a>,

pub fn with_params(path_prefix: &OsStr) -> Self

Create new instance of Synchronizer using given path_prefix and template parameters

pub fn write<T>( &'a mut self, entity: &T, grace_duration: Duration, ) -> Result<(usize, bool), SynchronizerError>

where T: Serialize<AllocSerializer<N>>, T::Archived: for<'b> CheckBytes<DefaultValidator<'b>>,

Writes a given entity into the next available data file.

Returns the number of bytes written to the data file and a boolean flag, for diagnostic purposes, indicating whether the reader counter was reset due to a reader exiting without decrementing it.

Parameters

• entity: The entity to be written to the data file.
• grace_duration: The maximum period to wait for readers to finish before resetting the reader count to 0. This handles scenarios where a reader process has crashed or exited abnormally, failing to decrement the reader count. After the grace_duration has elapsed, if there are still active readers, the reader count is reset to 0 to restore synchronization state.

Returns

A result containing a tuple of the number of bytes written and a boolean indicating whether the reader count was reset, or a SynchronizerError if the operation fails.

pub fn write_raw<T>( &'a mut self, data: &[u8], grace_duration: Duration, ) -> Result<(usize, bool), SynchronizerError>

where T: Serialize<AllocSerializer<N>>, T::Archived: for<'b> CheckBytes<DefaultValidator<'b>>,

Write raw data bytes representing type T into the next available data file. Returns number of bytes written to data file and a boolean flag, for diagnostic purposes, indicating that we have reset our readers counter after a reader died without decrementing it.

pub unsafe fn read<T>( &'a mut self, check_bytes: bool, ) -> Result<ReadResult<'_, T>, SynchronizerError>

where T: Archive, T::Archived: for<'b> CheckBytes<DefaultValidator<'b>>,

Reads and returns an entity struct from mapped memory wrapped in ReadGuard.

Parameters

• check_bytes: Whether to check that entity bytes can be safely read for type T, false - bytes check will not be performed (faster, but less safe), true - bytes check will be performed (slower, but safer).

Safety

This method is marked as unsafe due to the potential for memory corruption if the returned result is used beyond the grace_duration set in the write method. The caller must ensure the ReadGuard (and any references derived from it) are dropped before this time period elapses to ensure safe operation.

Additionally, the use of unsafe here is related to the internal use of the rkyv::archived_root function, which has its own safety considerations. Particularly, it assumes the byte slice provided to it accurately represents an archived object, and that the root of the object is stored at the end of the slice.

pub fn version(&'a mut self) -> Result<InstanceVersion, SynchronizerError>

Returns current InstanceVersion stored within the state, useful for detecting whether synchronized entity has changed.