Struct fslock::LockFile

pub struct LockFile { /* fields omitted */ }

A handle to a file that is lockable. Does not delete the file.

Multiple Handles/Descriptors To The Same File

The underlying file locking code behaves differently on Windows and Unix when the same process tries to lock the same file via two different LockFiles. See LockFile::open() for more information. You can work around this OS dependency by using LockFile::open_excl().

Example

use fslock::LockFile;

let mut file = LockFile::open("mylock.test")?;
file.lock()?;
do_stuff();
file.unlock()?;

Implementations

impl LockFile

pub fn open_excl<P>(path: &P) -> Result<Self, Error> where
    P: ToOsStr + ?Sized, 

Opens a file for locking. Exclusive here means the lock is exclusive to a file descriptor/handle on all platforms, instead of Unix’s behaviour of locking for the whole process. Do not confuse “exclusive” with the terminology of Linux’s and BSD’s flock system call.

On Unix, if the path is nul-terminated (ends with 0), no extra allocation will be made.

Panics

Panics if the path contains a nul-byte in a place other than the end.

Example

use fslock::LockFile;

let mut file = LockFile::open_excl("mylock.test")?;

Example with multiple locks.

use fslock::LockFile;

let mut lock1 = LockFile::open_excl("mylock.test")?;
let mut lock2 = LockFile::open_excl("mylock.test")?;

lock1.lock()?;
// We're holding the lock via lock1: locking via lock2 will fail.
assert_eq!(lock2.try_lock()?, false);

Panicking Example

use fslock::LockFile;

let mut file = LockFile::open("my\0lock")?;

Availability

This function is only available on Unix when the multilock feature is enabled.

pub fn open<P>(path: &P) -> Result<Self, Error> where
    P: ToOsStr + ?Sized, 

Opens a file for locking, with OS-dependent locking behavior. On Unix, if the path is nul-terminated (ends with 0), no extra allocation will be made.

Multiple Handles/Descriptors to the same file.

This function replicates the underlying OS behavior from file locking, which gives different results on Windows and Unix when the same process tries to lock the same file more than once.

Windows treats each handle to a file as having its own lock, whereas Unix treats all descriptors for a file as sharing a lock for the whole process. This means that on Windows you may open a file, lock it, open it again, and when you try to lock the second handle, it will block until the first lock is released. Meanwhile, Unix will check whether your process already owns the look, see that you already locked the file, and simply return as you already have the lock! It will only block if there is a different process holding the lock. Also, unlocking one file descriptor on unix will unlock the file for the whole process.

For consistent behavior across operating systems, you can either make sure that the same file is never locked more than once by the same process, or you can use the LockFile::open_excl() call instead (which requires multilock and std on Unix).

Compatibility

The lock files returned by this method can exhibit OS-dependent behavior: See “Multiple Handles/Descriptors To The Same File” in the documentation for LockFile.

Panics

Panics if the path contains a nul-byte in a place other than the end.

Example

use fslock::LockFile;

let mut file = LockFile::open("mylock.test")?;

Panicking Example

use fslock::LockFile;

let mut file = LockFile::open("my\0lock")?;

pub fn lock(&mut self) -> Result<(), Error>

Locks this file. Blocks while it is not possible to lock (i.e. someone else already owns a lock. After locked, if no attempt to unlock is made, it will be automatically unlocked on the file handle drop.

Panics

Panics if this handle already owns the file.

Example

use fslock::LockFile;

let mut file = LockFile::open("mylock.test")?;
file.lock()?;
do_stuff();
file.unlock()?;

Panicking Example

use fslock::LockFile;

let mut file = LockFile::open("mylock.test")?;
file.lock()?;
file.lock()?;

pub fn try_lock(&mut self) -> Result<bool, Error>

Locks this file. Does NOT block if it is not possible to lock (i.e. someone else already owns a lock. After locked, if no attempt to unlock is made, it will be automatically unlocked on the file handle drop.

Panics

Panics if this handle already owns the file.

Example

use fslock::LockFile;

let mut file = LockFile::open("mylock.test")?;
if file.try_lock()? {
    do_stuff();
    file.unlock()?;
}

Panicking Example

use fslock::LockFile;

let mut file = LockFile::open("mylock.test")?;
file.lock()?;
file.try_lock()?;

pub fn owns_lock(&self) -> bool

Returns whether this file handle owns the lock.

Example

use fslock::LockFile;

let mut file = LockFile::open("mylock.test")?;
do_stuff_with_lock(&mut file);
if !file.owns_lock() {
    file.lock()?;
    do_stuff();
    file.unlock()?;
}

pub fn unlock(&mut self) -> Result<(), Error>

Unlocks this file. This file handle must own the file lock. If not called manually, it is automatically called on drop.

Panics

Panics if this handle does not own the file.

Example

use fslock::LockFile;

let mut file = LockFile::open("mylock.test")?;
file.lock()?;
do_stuff();
file.unlock()?;

Panicking Example

use fslock::LockFile;

let mut file = LockFile::open("mylock.test")?;
file.unlock()?;

Trait Implementations

impl Debug for LockFile

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for LockFile

fn drop(&mut self)

Executes the destructor for this type.

impl Send for LockFile

impl Sync for LockFile