Struct fslock::LockFile [−][src]
pub struct LockFile { /* fields omitted */ }
Expand description
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
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")?;
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()?;
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(())
}
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()?;
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()?;
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()?;
}
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()?;