Struct WatchLock 

pub struct WatchLock { /* private fields */ }

Advisory file lock for cross-process watch coordination.

The writer process acquires an exclusive lock, and reader processes can check whether a writer is active before polling for changes.

The lock is automatically released when this struct is dropped.

Example

use pulsedb::WatchLock;

// Writer process
let lock = WatchLock::acquire_exclusive(&db_path)?;
// ... write experiences ...
drop(lock); // releases lock

// Reader process
if WatchLock::is_writer_active(&db_path) {
    let seq = db.get_current_sequence()?;
    let (events, _new_seq) = db.poll_changes(seq)?;
}

Implementations

impl WatchLock

pub fn acquire_exclusive(db_path: &Path) -> Result<Self>

Acquires an exclusive lock (for the writer process).

Blocks until the lock is available. Only one exclusive lock can be held at a time.

Errors

Returns an error if the lock file cannot be created or locked.

pub fn acquire_shared(db_path: &Path) -> Result<Self>

Acquires a shared lock (for reader processes).

Multiple shared locks can coexist. A shared lock blocks exclusive locks from being acquired.

Errors

Returns an error if the lock file cannot be created or locked.

pub fn try_exclusive(db_path: &Path) -> Result<Option<Self>>

Tries to acquire an exclusive lock without blocking.

Returns Ok(Some(lock)) if acquired, Ok(None) if another process holds the lock.

pub fn is_writer_active(db_path: &Path) -> bool

Checks whether a writer currently holds the exclusive lock.

This is a non-blocking check. Returns true if an exclusive lock is held (writer is active), false otherwise.

Note: This has a TOCTOU race — the writer could start or stop between this check and any subsequent action. Use it as a hint, not a guarantee.

pub fn path(&self) -> &Path

Returns the path to the lock file.

Trait Implementations

impl Debug for WatchLock

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.