Struct LockFile

pub struct LockFile { /* private fields */ }

A handle to a file that is lockable. Does not delete the file. On both Unix and Windows, the lock is held by an individual handle, and not by the whole process. On Unix, however, under fork file descriptors might be duplicated sharing the same lock, but fork is usually unsafe in Rust.

Example

use fslock::LockFile;

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

Implementations

impl LockFile

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.

Compatibility

This crate used to behave differently in regards to Unix and Windows, when locks on Unix were per-process and not per-handle. However, the current version locks per-handle on any platform. On Unix, however, under fork file descriptors might be duplicated sharing the same lock, but fork is usually unsafe in Rust.

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("testfiles/regular.lock")?;

Panicking Example

use fslock::LockFile;

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

Examples found in repository

examples/locks_until_nl.rs (line 18)

fn main() -> Result<(), fslock::Error> {
    let mut args = env::args();
    args.next();

    let path = match args.next() {
        Some(arg) if args.next().is_none() => arg,
        _ => {
            eprintln!("Expected one argument");
            process::exit(1);
        },
    };
    let mut lockfile = LockFile::open(&path)?;
    lockfile.lock()?;
    io::stdin().read(&mut [0; 1])?;

    Ok(())
}

examples/try_lock.rs (line 19)

fn main() -> Result<(), fslock::Error> {
    let mut args = env::args();
    args.next();

    let path = match args.next() {
        Some(arg) if args.next().is_none() => arg,
        _ => {
            eprintln!("Expected one argument");
            process::exit(1);
        },
    };

    let mut lockfile = LockFile::open(&path)?;

    if lockfile.try_lock()? {
        println!("SUCCESS");
    } else {
        println!("FAILURE");
    }

    Ok(())
}

examples/try_lock_with_pid.rs (line 19)

fn main() -> Result<(), fslock::Error> {
    let mut args = env::args();
    args.next();

    let path = match args.next() {
        Some(arg) if args.next().is_none() => arg,
        _ => {
            eprintln!("Expected one argument");
            process::exit(1);
        },
    };

    let mut lockfile = LockFile::open(&path)?;

    if lockfile.try_lock_with_pid()? {
        let content_a = read_to_string(&path)?;
        let content_b = read_to_string(&path)?;
        assert!(content_a.trim().len() > 0);
        assert!(content_a.trim().chars().all(|ch| ch.is_ascii_digit()));
        assert_eq!(content_a, content_b);

        println!("{}", content_a);
    } else {
        println!("FAILURE");
    }

    Ok(())
}

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("testfiles/target.lock")?;
file.lock()?;
do_stuff();
file.unlock()?;

Panicking Example

use fslock::LockFile;

let mut file = LockFile::open("testfiles/panicking.lock")?;
file.lock()?;
file.lock()?;

Examples found in repository

examples/locks_until_nl.rs (line 19)

fn main() -> Result<(), fslock::Error> {
    let mut args = env::args();
    args.next();

    let path = match args.next() {
        Some(arg) if args.next().is_none() => arg,
        _ => {
            eprintln!("Expected one argument");
            process::exit(1);
        },
    };
    let mut lockfile = LockFile::open(&path)?;
    lockfile.lock()?;
    io::stdin().read(&mut [0; 1])?;

    Ok(())
}

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

Locks this file and writes this process’s PID into the file, which will be erased on unlock. Like LockFile::lock, blocks while it is not possible to 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;
use std::fs::read_to_string;

let mut file = LockFile::open("testfiles/withpid.lock")?;
file.lock_with_pid()?;
do_stuff()?;
file.unlock()?;

fn do_stuff() -> Result<(), fslock::Error> {
    let mut content = read_to_string("testfiles/withpid.lock")?;
    assert!(content.trim().len() > 0);
    assert!(content.trim().chars().all(|ch| ch.is_ascii_digit()));
    Ok(())
}

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("testfiles/attempt.lock")?;
if file.try_lock()? {
    do_stuff();
    file.unlock()?;
}

Panicking Example

use fslock::LockFile;

let mut file = LockFile::open("testfiles/attempt_panic.lock")?;
file.lock()?;
file.try_lock()?;

Examples found in repository

examples/try_lock.rs (line 21)

fn main() -> Result<(), fslock::Error> {
    let mut args = env::args();
    args.next();

    let path = match args.next() {
        Some(arg) if args.next().is_none() => arg,
        _ => {
            eprintln!("Expected one argument");
            process::exit(1);
        },
    };

    let mut lockfile = LockFile::open(&path)?;

    if lockfile.try_lock()? {
        println!("SUCCESS");
    } else {
        println!("FAILURE");
    }

    Ok(())
}

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

Locks this file and writes this process’s PID into the file, which will be erased on unlock. 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("testfiles/pid_attempt.lock")?;
if file.try_lock_with_pid()? {
    do_stuff()?;
    file.unlock()?;
}

fn do_stuff() -> Result<(), fslock::Error> {
    let mut content = read_to_string("testfiles/pid_attempt.lock")?;
    assert!(content.trim().len() > 0);
    assert!(content.trim().chars().all(|ch| ch.is_ascii_digit()));
    Ok(())
}

Panicking Example

use fslock::LockFile;

let mut file = LockFile::open("testfiles/pid_attempt_panic.lock")?;
file.lock_with_pid()?;
file.try_lock_with_pid()?;

Examples found in repository

examples/try_lock_with_pid.rs (line 21)

fn main() -> Result<(), fslock::Error> {
    let mut args = env::args();
    args.next();

    let path = match args.next() {
        Some(arg) if args.next().is_none() => arg,
        _ => {
            eprintln!("Expected one argument");
            process::exit(1);
        },
    };

    let mut lockfile = LockFile::open(&path)?;

    if lockfile.try_lock_with_pid()? {
        let content_a = read_to_string(&path)?;
        let content_b = read_to_string(&path)?;
        assert!(content_a.trim().len() > 0);
        assert!(content_a.trim().chars().all(|ch| ch.is_ascii_digit()));
        assert_eq!(content_a, content_b);

        println!("{}", content_a);
    } else {
        println!("FAILURE");
    }

    Ok(())
}

pub fn owns_lock(&self) -> bool

Returns whether this file handle owns the lock.

Example

use fslock::LockFile;

let mut file = LockFile::open("testfiles/maybeowned.lock")?;
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("testfiles/endinglock.lock")?;
file.lock()?;
do_stuff();
file.unlock()?;

Panicking Example

use fslock::LockFile;

let mut file = LockFile::open("testfiles/endinglock.lock")?;
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.