fd-lock

fd-lock is a small Rust crate that provides advisory, cross-platform file locking through a file’s descriptor (or handle on Windows). It wraps a file in an RwLock-style type so that cooperating processes can coordinate read and write access to a shared file, using flock-style locking on Unix and the equivalent Windows APIs underneath a single portable interface.

The locks are advisory, meaning compliance is opt-in and can be ignored by any party that does not also take the lock, so the crate is meant purely for coordination between cooperating programs and explicitly not for security or access control. Its API deliberately mirrors the standard library’s RwLock, returning read and write guards that release the lock when dropped.

What You Get

• An RwLock<File> type modeled on std::sync::RwLock
• Advisory read and write locks backed by the file descriptor or handle
• Cross-platform support using flock-style locking on Unix and Windows APIs
• RAII guards that hold the lock across multiple operations and release on drop

Common Use Cases

• Preventing two instances of a tool from writing the same file at once
• Coordinating access to a shared state or database file between processes
• Implementing single-instance locks for CLI applications and daemons

Under The Hood

Architecture - The crate is deliberately small: src/rw_lock.rs defines the RwLock<T> wrapper around a file-like value, and src/read_guard.rs and src/write_guard.rs implement RAII guards that acquire the OS lock on creation and release it on Drop. Platform-specific locking lives under src/sys, which selects flock-style calls on Unix and the corresponding Windows locking APIs, keeping the public type identical across targets.

Tech Stack - Rust over raw file descriptors on Unix and windows-sys on Windows, with a small amount of carefully audited unsafe on the Windows path. It has no runtime dependencies beyond the platform bindings and builds as a plain Cargo crate with no build script.

Code Quality - The codebase is compact, mature, and extremely widely used (tens of millions of downloads), adapted from the established mafintosh/fd-lock. The README is explicit about safety invariants and the advisory-only nature of the locks, and the maintainers document that all unsafe invariants are manually enforced.

API Design - By mirroring std::sync::RwLock, the API is immediately intuitive: wrap a File in RwLock::new, then call read() or write() to get a guard you can read from or write through. RAII release means callers rarely have to think about unlocking, so the ergonomic cost of correct cross-process locking is minimal.