fslock

fslock is a small, dependency-light Rust crate that lets you use files as locks to coordinate between processes. It exposes a single LockFile type whose methods map to the native locking facilities of each platform - flock/fcntl on Unix and LockFileEx on Windows - behind one consistent, safe API.

Beyond simple acquire-and-release, fslock offers non-blocking try_lock variants, methods that stamp the holder’s PID into the lock file, automatic release when the handle is dropped, and an optional no_std build for constrained environments. It is a practical building block for single-instance daemons, CLI tools, and any code that needs cross-process mutual exclusion.

What You Get

• A single LockFile type with open, lock, try_lock, unlock, and owns_lock methods
• PID-writing variants (lock_with_pid, try_lock_with_pid) that record which process holds the lock
• Unified Unix and Windows backends selected at compile time behind one API
• Optional no_std support plus AsFd/AsHandle integration when the std feature is enabled

Common Use Cases

• Ensuring only one instance of a process runs at a time
• Serializing access to a shared file or directory across separate processes
• Recording which process currently holds a lock via its PID

Under The Hood

Architecture The public surface lives in src/lib.rs, which defines the LockFile struct wrapping an OS file descriptor/handle plus a locked bool. All platform work is delegated to a sys module aliased at compile time via #[cfg(unix)]/#[cfg(windows)] to src/unix.rs or src/windows.rs, so lock, try_lock, unlock, truncate, pid, and close each have two implementations behind one signature. String handling is abstracted through the ToOsStr/IntoOsString traits in src/string.rs, and PID writing reuses a tiny fmt::Writer in src/fmt.rs.

Tech Stack Written in Rust (edition 2018) with a deliberately minimal dependency set: libc on Unix and winapi (with a curated feature list covering fileapi, synchapi, handleapi, etc.) on Windows, both pulled in only for their target. A std feature is enabled by default; disabling it activates a no_std build that even hand-declares the platform-specific errno symbol so it can drop the standard library.

Code Quality The crate is small and carefully written. Unsafe FFI calls are localized to the platform modules and annotated with SAFETY comments (for example around AsFd/AsHandle and the Windows Send/Sync impls). Nearly every public method carries doctested examples, including should_panic cases documenting misuse, and src/test.rs holds integration-style tests exercising PID reading and lock contention against real files in testfiles/.

API Design The API is compact and hard to misuse: open then lock/try_lock/unlock, with owns_lock to query state and PID-writing variants for diagnostics. Ergonomics come from the Drop impl that auto-unlocks and closes, generic path acceptance via ToOsStr, and standard AsRawFd/AsRawHandle conversions under std. The naming is consistent and the getting-started boilerplate is essentially three lines.