Trait fs2::FileExt [−] [src]

pub trait FileExt {
    fn duplicate(&self) -> Result<File>;
    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<()>;
}

Extension trait for File providing 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

fn duplicate(&self) -> Result<File>

Returns a duplicate instance of the file.

The returned file will share the same file position as the original file.

Notes

This is implemented with dup(2) on Unix and DuplicateHandle on Windows.

fn lock_shared(&self) -> Result<()>

Locks the file for shared usage, blocking if the file is currently locked exclusively.

fn lock_exclusive(&self) -> Result<()>

Locks the file for exclusive usage, blocking if the file is currently locked.

fn try_lock_shared(&self) -> Result<()>

Locks the file for shared usage, or returns a an error if the file is currently locked (see lock_contended_error).

fn try_lock_exclusive(&self) -> Result<()>

Locks the file for shared usage, or returns a an error if the file is currently locked (see lock_contended_error).

fn unlock(&self) -> Result<()>

Unlocks the file.

Implementors