pub struct ShmReader { /* private fields */ }Expand description
Reader for ClockBound daemon shared memory segment.
The Clockbound daemon shared memory segment consists of a ShmHeader followed by a
ClockBoundError struct. The segment is updated by a single producer (the clockbound daemon),
but may be read by many clients. The shared memory segment does not implement a semaphore or
equivalent to synchronize the single-producer / many-consumers processes. Instead, the
mechanism is lock-free and relies on a generation number to ensure consistent reads (over
retries).
The writer increments the generation field from even to odd before each update. It also
increment it again, from odd to even, after finishing the update. Readers must check the
generation field before and after each read, and verify that they obtain the same, even,
value. Otherwise, the read was dirty and must be retried.
Implementations§
Source§impl ShmReader
impl ShmReader
Sourcepub fn new(path: &CStr) -> Result<ShmReader, ShmError>
pub fn new(path: &CStr) -> Result<ShmReader, ShmError>
Open a ClockBound shared memory segment for reading.
On error, returns an appropriate Errno. If the content of the segment
is uninitialized, unparseable, or otherwise malformed, EPROTO will be
returned.
Sourcepub fn snapshot(&mut self) -> Result<&ClockErrorBound, ShmError>
pub fn snapshot(&mut self) -> Result<&ClockErrorBound, ShmError>
Return a consistent snapshot of the shared memory segment.
Taking a snapshot consists in reading the memory segment while confirming the generation number in the header has not changed (which would indicate an update from the writer occurred while reading). If an update is detected, the read is retried.
This function returns a reference to the ClockErrorBound snapshot stored by the reader, and not an owned value. This make the ShmReader NOT thread-safe: the data pointed to could be updated without one of the thread knowing, leading to a incorrect clock error bond. The advantage are in terms of performance: less data copied, but also no locking, yielding or excessive retries.