pub trait FileExt {
// Required methods
fn allocated_size(&self) -> Result<u64>;
fn allocate(&self, len: u64) -> Result<()>;
fn lock_shared(&self) -> Result<()>;
fn lock_exclusive(&self) -> Result<()>;
fn try_lock_shared(&self) -> Result<()>;
fn try_lock_exclusive(&self) -> Result<()>;
fn unlock(&self) -> Result<()>;
}
Expand description
Extension trait for std::fs::File
which provides allocation, duplication and locking methods.
§Notes on File Locks
This library provides whole-file locks in both shared (read) and exclusive (read-write) varieties.
File locks are a cross-platform hazard since the file lock APIs exposed by operating system kernels vary in subtle and not-so-subtle ways.
The API exposed by this library can be safely used across platforms as long as the following rules are followed:
- Multiple locks should not be created on an individual
File
instance concurrently. - Duplicated files should not be locked without great care.
- Files to be locked should be opened with at least read or write permissions.
- File locks may only be relied upon to be advisory.
See the tests in lib.rs
for cross-platform lock behavior that may be
relied upon; see the tests in unix.rs
and windows.rs
for examples of
platform-specific behavior. File locks are implemented with
flock(2)
on Unix and
LockFile
on Windows.
Required Methods§
Sourcefn allocated_size(&self) -> Result<u64>
fn allocated_size(&self) -> Result<u64>
Returns the amount of physical space allocated for a file.
Sourcefn allocate(&self, len: u64) -> Result<()>
fn allocate(&self, len: u64) -> Result<()>
Ensures that at least len
bytes of disk space are allocated for the
file, and the file size is at least len
bytes. After a successful call
to allocate
, subsequent writes to the file within the specified length
are guaranteed not to fail because of lack of disk space.
Locks the file for shared usage, blocking if the file is currently locked exclusively.
Sourcefn lock_exclusive(&self) -> Result<()>
fn lock_exclusive(&self) -> Result<()>
Locks the file for exclusive usage, blocking if the file is currently locked.
Locks the file for shared usage, or returns an error if the file is
currently locked (see lock_contended_error
).
Sourcefn try_lock_exclusive(&self) -> Result<()>
fn try_lock_exclusive(&self) -> Result<()>
Locks the file for exclusive usage, or returns an error if the file is
currently locked (see lock_contended_error
).