Struct VMClockShmReader

pub struct VMClockShmReader { /* private fields */ }

Reader for VMClock shared memory segment.

The VMClock shared memory segment consists of a VMClockShmHeader followed by a VMClockShmBody struct. The segment is updated by a single producer (the Hypervisor), 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 seq_count number to ensure consistent reads (over retries).

The writer increments the seq_count 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 seq_count 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

impl VMClockShmReader

pub fn new(path: &str) -> Result<VMClockShmReader, ShmError>

Open a VMClock 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.

pub fn snapshot(&mut self) -> Result<&VMClockShmBody, ShmError>

Return a consistent snapshot of the shared memory segment.

Taking a snapshot consists in reading the memory segment while confirming the seq_count 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 VMClockShmBody snapshot stored by the reader, and not an owned value. This make the VMClockShmReader 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.