Mutual exclusion across processes on a file descriptor or path.
- On Unix-like systems this is implemented use
flock(2). - On Windows this is implemented using
LockFileEx.
First add fmutex to your Cargo manifest.
cargo add fmutexNow use one of the provided functions to lock a file descriptor (Unix) or handle (Windows) or a file path.
For exclusive locks (only one process can hold the lock):
lock_exclusive()to acquire an exclusive lock on a file descriptor or handle.try_lock_exclusive()to attempt to acquire an exclusive lock on a file descriptor or handle.lock_exclusive_path()to acquire an exclusive lock on a file path.try_lock_exclusive_path()to attempt to acquire an exclusive lock on a file path.
For shared locks (multiple processes can hold the lock simultaneously, but not when an exclusive lock is held):
lock_shared()to acquire a shared lock on a file descriptor or handle.try_lock_shared()to attempt to acquire a shared lock on a file descriptor or handle.lock_shared_path()to acquire a shared lock on a file path.try_lock_shared_path()to attempt to acquire a shared lock on a file path.
let fd = fs::OpenOptions::new().create(true).write(true).open(&path)?;
{
let _guard = fmutex::lock_exclusive(&fd)?;
// do mutually exclusive stuff here
} // <-- `_guard` dropped here and the lock is releasedlet fd = fs::OpenOptions::new().create(true).write(true).open(&path)?;
match fmutex::try_lock_exclusive(&fd)? {
Some(_guard) => {
// do mutually exclusive stuff here
} // <-- `_guard` dropped here and the lock is released
None => {
eprintln!("the lock could not be acquired!");
}
}let path = "path/to/my/file.txt";
{
let _guard = fmutex::lock_exclusive_path(path)?;
// do mutually exclusive stuff here
} // <-- `_guard` dropped here and the lock is releasedlet path = "path/to/my/file.txt";
match fmutex::try_lock_exclusive_path(path)? {
Some(_guard) => {
// do mutually exclusive stuff here
} // <-- `_guard` dropped here and the lock is released
None => {
eprintln!("the lock could not be acquired!");
}
}let fd = fs::OpenOptions::new().create(true).write(true).open(&path)?;
{
let _guard = fmutex::lock_shared(&fd)?;
// do shared read-only operations here
// other processes can also acquire shared locks simultaneously
} // <-- `_guard` dropped here and the lock is releasedlet fd = fs::OpenOptions::new().create(true).write(true).open(&path)?;
match fmutex::try_lock_shared(&fd)? {
Some(_guard) => {
// do shared read-only operations here
// other processes can also acquire shared locks simultaneously
} // <-- `_guard` dropped here and the lock is released
None => {
eprintln!("the shared lock could not be acquired (file is exclusively locked)!");
}
}let path = "path/to/my/file.txt";
{
let _guard = fmutex::lock_shared_path(path)?;
// do shared read-only operations here
// other processes can also acquire shared locks simultaneously
} // <-- `_guard` dropped here and the lock is releasedlet path = "path/to/my/file.txt";
match fmutex::try_lock_shared_path(path)? {
Some(_guard) => {
// do shared read-only operations here
// other processes can also acquire shared locks simultaneously
} // <-- `_guard` dropped here and the lock is released
None => {
eprintln!("the shared lock could not be acquired (file is exclusively locked)!");
}
}This project is distributed under the terms of both the MIT license and the Apache License (Version 2.0).
See LICENSE-APACHE and LICENSE-MIT for details.