Struct Filesystem

pub struct Filesystem { /* private fields */ }

A “filesystem” is intended to be a globally shared, hence locked, resource in Cargo.

The Path of a filesystem cannot be learned unless it’s done in a locked fashion, and otherwise functions on this structure are prepared to handle concurrent invocations across multiple instances of Cargo.

The methods on Filesystem that open files return a FileLock which holds the lock, and that type provides methods for accessing the underlying file.

If the blocking methods (like Filesystem::open_ro_shared) detect that they will block, then they will display a message to the user letting them know it is blocked. There are non-blocking variants starting with the try_ prefix like Filesystem::try_open_ro_shared_create.

The behavior of locks acquired by the Filesystem depend on the operating system. On unix-like system, they are advisory using flock, and thus not enforced against processes which do not try to acquire the lock. On Windows, they are mandatory using LockFileEx, enforced against all processes.

This does not guarantee that a lock is acquired. In some cases, for example on filesystems that don’t support locking, it will return a FileLock even though the filesystem lock was not acquired. This is intended to provide a graceful fallback instead of refusing to work. Usually there aren’t multiple processes accessing the same resource. In that case, it is the user’s responsibility to not run concurrent processes.

Implementations

impl Filesystem

pub fn new(path: PathBuf) -> Filesystem

Creates a new filesystem to be rooted at the given path.

pub fn join<T: AsRef<Path>>(&self, other: T) -> Filesystem

Like Path::join, creates a new filesystem rooted at this filesystem joined with the given path.

pub fn push<T: AsRef<Path>>(&mut self, other: T)

Like Path::push, pushes a new path component onto this filesystem.

pub fn into_path_unlocked(self) -> PathBuf

Consumes this filesystem and returns the underlying PathBuf.

Note that this is a relatively dangerous operation and should be used with great caution!.

pub fn as_path_unlocked(&self) -> &Path

Returns the underlying Path.

Note that this is a relatively dangerous operation and should be used with great caution!.

pub fn create_dir(&self) -> Result<()>

Creates the directory pointed to by this filesystem.

Handles errors where other Cargo processes are also attempting to concurrently create this directory.

pub fn display(&self) -> Display<'_>

Returns an adaptor that can be used to print the path of this filesystem.

pub fn open_rw_exclusive_create<P>( &self, path: P, msg: &str, ) -> Result<FileLock>

where P: AsRef<Path>,

Opens read-write exclusive access to a file, returning the locked version of a file.

This function will create a file at path if it doesn’t already exist (including intermediate directories), and then it will acquire an exclusive lock on path. If the process must block waiting for the lock, the msg is printed to stderr.

The returned file can be accessed to look at the path and also has read/write access to the underlying file.

pub fn try_open_rw_exclusive_create<P: AsRef<Path>>( &self, path: P, ) -> Result<Option<FileLock>>

A non-blocking version of Filesystem::open_rw_exclusive_create.

Returns None if the operation would block due to another process holding the lock.

pub fn open_ro_shared<P>(&self, path: P, msg: &str) -> Result<FileLock>

where P: AsRef<Path>,

Opens read-only shared access to a file, returning the locked version of a file.

This function will fail if path doesn’t already exist, but if it does then it will acquire a shared lock on path. If the process must block waiting for the lock, the msg is printed to stderr.

The returned file can be accessed to look at the path and also has read access to the underlying file. Any writes to the file will return an error.

pub fn open_ro_shared_create<P: AsRef<Path>>( &self, path: P, msg: &str, ) -> Result<FileLock>

Opens read-only shared access to a file, returning the locked version of a file.

Compared to Filesystem::open_ro_shared, this will create the file (and any directories in the parent) if the file does not already exist.

pub fn try_open_ro_shared_create<P: AsRef<Path>>( &self, path: P, ) -> Result<Option<FileLock>>

A non-blocking version of Filesystem::open_ro_shared_create.

Returns None if the operation would block due to another process holding the lock.

Trait Implementations

impl Clone for Filesystem

fn clone(&self) -> Filesystem

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Filesystem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq<Filesystem> for Path

fn eq(&self, other: &Filesystem) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Path> for Filesystem

fn eq(&self, other: &Path) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.