Struct SharedFile

pub struct SharedFile { /* private fields */ }

This struct implements an “advisory lock” of a file using an auxiliary lock file to control the shared read access to the file as well as an exclusive read and write access to it.

Internally, it uses the crate fd-lock to control the access to the lock file while protecting the access tot the actual file.

The protected file is always opened with shared read and write and create options.

Locking the same file in multiple threads

It is very important to notice that this struct is not thread safe and must be protected by a Mutex whenever necessary. It happens because the file offset pointer cannot be safely shared among multiple threads even for read operations. Unfortunately, the use of the mutex or other sync mechanisms will lead to the serialization of both read and write locks inside the same application.

Because of that, it is recommended to create multiple instances of this struct pointing to the same file. The access control will be guaranteed by the use of the lock file instead of the traditional thread sync mechanisms.

Implementations

impl SharedFile

pub fn new(file: &Path) -> Result<Self>

Creates a new SharedFile. The name of the lock file will be determine automatically based on the name of the original file.

The shared file is opened with the Self::default_options().

Arguments:

• file: The file to be protected;

Returns the new instance of an IO error to indicate what went wrong.

pub fn with_options(file: &Path, options: &OpenOptions) -> Result<Self>

Creates a new SharedFile. The name of the lock file will be determine automatically based on the name of the original file.

Arguments:

• file: The file to be protected;
• options: OpenOptions used to open the file;

Returns the new instance of an IO error to indicate what went wrong.

pub fn with_option_builder( file: &Path, options: &OpenOptions, lock_file_builder: &dyn SharedFileLockNameBuilder, ) -> Result<Self>

Creates a new SharedFile. The name of the lock file will be determine by the specified SharedFileLockNameBuilder.

Arguments:

• file: The file to be protected;
• options: OpenOptions used to open the file;
• lock_file_builder: The lock file builder to use;

Returns the new instance of an IO error to indicate what went wrong.

pub fn with_option_lock_file( file: &Path, options: &OpenOptions, lock_file: &Path, ) -> Result<Self>

Creates a new SharedFile.

Arguments:

• file: The file to be protected;
• options: OpenOptions used to open the file;
• lock_file: The lock file to use;

Returns the new instance of an IO error to indicate what went wrong.

pub fn default_options() -> OpenOptions

Returns the default open options used to open the target file. It sets read write and create to true.

pub fn read(&mut self) -> Result<SharedFileReadLockGuard<'_>>

Locks the file for shared read.

Returns read lock that grants access to the file.

pub fn write(&mut self) -> Result<SharedFileWriteLockGuard<'_>>

Locks the file for exclusive write and read

Returns read/write lock that grants access to the file.

pub fn try_read(&mut self) -> Result<SharedFileReadLockGuard<'_>>

Attempts to locks the file for shared read. It fails without waiting if the lock cannot be acquired.

Returns read lock that grants access to the file.

pub fn try_write(&mut self) -> Result<SharedFileWriteLockGuard<'_>>

Attempts to acquire the file lock for exclusive write and read. It fails without waiting if the lock cannot be acquired.

Returns read/write lock that grants access to the file.