Struct DatabaseLock 

pub struct DatabaseLock { /* private fields */ }

Exclusive advisory lock on a database directory

This lock ensures single-process access to a SochDB database. The lock is automatically released when this struct is dropped.

Implementation

Uses POSIX flock() on Unix systems and LockFileEx() on Windows. The lock file also contains the PID of the lock holder for debugging and stale lock detection.

Safety

Advisory locks are cooperative - they only work if all processes attempting to access the database use this locking mechanism.

Implementations

impl DatabaseLock

pub fn acquire<P: AsRef<Path>>(db_path: P) -> Result<Self, LockError>

Acquire exclusive lock on a database directory

Uses the default timeout (5 seconds) to allow concurrent processes to wait for the lock, similar to SQLite’s busy timeout behavior. This enables multi-process patterns like ProcessPoolExecutor where each worker serializes database access through lock contention.

Arguments

• db_path - Path to the database directory

Returns

Returns Ok(DatabaseLock) if lock acquired successfully. Returns Err(LockError::Timeout) if lock not acquired within 5 seconds. Returns Err(LockError::DatabaseLocked) if another process holds the lock and stale lock detection fails.

Example

let lock = DatabaseLock::acquire("/path/to/db")?;
// Lock is held until `lock` is dropped

pub fn acquire_no_wait<P: AsRef<Path>>(db_path: P) -> Result<Self, LockError>

Acquire exclusive lock without waiting (fail immediately if locked)

Use this only when you want to detect if another process has the database open, without blocking.

pub fn acquire_with_timeout<P: AsRef<Path>>( db_path: P, timeout: Duration, ) -> Result<Self, LockError>

Acquire exclusive lock with timeout

Will retry lock acquisition until timeout expires.

Arguments

• db_path - Path to the database directory
• timeout - Maximum time to wait for lock

pub fn acquire_with_config<P: AsRef<Path>>( db_path: P, config: &LockConfig, ) -> Result<Self, LockError>

Acquire exclusive lock with full configuration

pub fn path(&self) -> &Path

Get path to the lock file

pub fn pid(&self) -> u32

Get PID of lock holder (us)

pub fn get_lock_holder<P: AsRef<Path>>(db_path: P) -> Option<u32>

Check if a given PID is holding the lock on a database

Useful for diagnostics without attempting to acquire.

Trait Implementations

impl Drop for DatabaseLock

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.