Crate fmutex

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.

🚀 Getting started

First add fmutex to your Cargo manifest.

cargo add fmutex

Now 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.

🤸 Usage

lock_exclusive()

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 released

try_lock_exclusive()

let 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!");
    }
}

lock_exclusive_path()

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 released

try_lock_exclusive_path()

let 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!");
    }
}

lock_shared()

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 released

try_lock_shared()

let 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)!");
    }
}

lock_shared_path()

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 released

try_lock_shared_path()

let 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)!");
    }
}

Structs

BorrowedResource

Cross-platform version of BorrowedFd and BorrowedHandle.

Guard

When this structure is dropped, the file will be unlocked.

Traits

AsResource

Cross-platform version of AsFd and AsHandle.

Functions

lock_exclusive

Acquires an exclusive lock on the resource, blocking the current thread until it can.

lock_exclusive_path

Acquires an exclusive lock for the file at the given path, blocking the current thread until it can.

lock_shared

Acquires a shared lock on the resource, blocking the current thread until it can.

lock_shared_path

Acquires a shared lock for the file at the given path, blocking the current thread until it can.

try_lock_exclusive

Attempts to acquire an exclusive lock on the resource, returning None if it is locked.

try_lock_exclusive_path

Attempts to acquire an exclusive lock for the file at the given path, returning None if it is locked.

try_lock_shared

Attempts to acquire a shared lock on the resource, returning None if it is exclusively locked.

try_lock_shared_path

Attempts to acquire a shared lock for the file at the given path, returning None if it is exclusively locked.