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