user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Reword file lock documentation to clarify advisory vs mandatory

Browse source 
Remove the word "advisory", and make it more explicit that the lock may
be advisory or mandatory depending on platform.
This commit is contained in:
Josh Triplett 2025-02-11 17:48:36 +01:00
parent 8c61cd4df8
commit 16abb39c9d
1 changed files with 40 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

75
library/std/src/fs.rs
View file

@ -624,20 +624,20 @@ impl File {
self.inner.datasync()
}
/// Acquire an exclusive advisory lock on the file. Blocks until the lock can be acquired.
/// Acquire an exclusive lock on the file. Blocks until the lock can be acquired.
///
/// This acquires an exclusive advisory lock; no other file handle to this file may acquire
/// another lock.
/// This acquires an exclusive lock; no other file handle to this file may acquire another lock.
///
/// If this file handle/descriptor, or a clone of it, already holds an advisory lock the exact
/// behavior is unspecified and platform dependent, including the possibility that it will
/// deadlock. However, if this method returns, then an exclusive lock is held.
/// If this file handle/descriptor, or a clone of it, already holds an lock the exact behavior
/// is unspecified and platform dependent, including the possibility that it will deadlock.
/// However, if this method returns, then an exclusive lock is held.
///
/// If the file not open for writing, it is unspecified whether this function returns an error.
///
/// Note, this is an advisory lock meant to interact with [`lock_shared`], [`try_lock`],
/// [`try_lock_shared`], and [`unlock`]. Its interactions with other methods, such as [`read`]
/// and [`write`] are platform specific, and it may or may not cause non-lockholders to block.
/// This lock may be advisory or mandatory. This lock is meant to interact with [`lock`],
/// [`try_lock`], [`lock_shared`], [`try_lock_shared`], and [`unlock`]. Its interactions with
/// other methods, such as [`read`] and [`write`] are platform specific, and it may or may not
/// cause non-lockholders to block.
///
/// The lock will be released when this file (along with any other file descriptors/handles
/// duplicated or inherited from it) is closed, or if the [`unlock`] method is called.
@ -650,6 +650,7 @@ impl File {
///
/// [changes]: io#platform-specific-behavior
///
/// [`lock`]: File::lock
/// [`lock_shared`]: File::lock_shared
/// [`try_lock`]: File::try_lock
/// [`try_lock_shared`]: File::try_lock_shared
@ -674,18 +675,19 @@ impl File {
self.inner.lock()
}
/// Acquire a shared (non-exclusive) advisory lock on the file. Blocks until the lock can be acquired.
/// Acquire a shared (non-exclusive) lock on the file. Blocks until the lock can be acquired.
///
/// This acquires a shared advisory lock; more than one file handle may hold a shared lock, but
/// none may hold an exclusive lock at the same time.
/// This acquires a shared lock; more than one file handle may hold a shared lock, but none may
/// hold an exclusive lock at the same time.
///
/// If this file handle/descriptor, or a clone of it, already holds an advisory lock, the exact
/// behavior is unspecified and platform dependent, including the possibility that it will
/// deadlock. However, if this method returns, then a shared lock is held.
/// If this file handle/descriptor, or a clone of it, already holds an lock, the exact behavior
/// is unspecified and platform dependent, including the possibility that it will deadlock.
/// However, if this method returns, then a shared lock is held.
///
/// Note, this is an advisory lock meant to interact with [`lock`], [`try_lock`],
/// [`try_lock_shared`], and [`unlock`]. Its interactions with other methods, such as [`read`]
/// and [`write`] are platform specific, and it may or may not cause non-lockholders to block.
/// This lock may be advisory or mandatory. This lock is meant to interact with [`lock`],
/// [`try_lock`], [`lock_shared`], [`try_lock_shared`], and [`unlock`]. Its interactions with
/// other methods, such as [`read`] and [`write`] are platform specific, and it may or may not
/// cause non-lockholders to block.
///
/// The lock will be released when this file (along with any other file descriptors/handles
/// duplicated or inherited from it) is closed, or if the [`unlock`] method is called.
@ -699,6 +701,7 @@ impl File {
/// [changes]: io#platform-specific-behavior
///
/// [`lock`]: File::lock
/// [`lock_shared`]: File::lock_shared
/// [`try_lock`]: File::try_lock
/// [`try_lock_shared`]: File::try_lock_shared
/// [`unlock`]: File::unlock
@ -722,24 +725,23 @@ impl File {
self.inner.lock_shared()
}
/// Try to acquire an exclusive advisory lock on the file.
/// Try to acquire an exclusive lock on the file.
///
/// Returns `Ok(false)` if a different lock is already held on this file (via another
/// handle/descriptor).
///
/// This acquires an exclusive advisory lock; no other file handle to this file may acquire
/// another lock.
/// This acquires an exclusive lock; no other file handle to this file may acquire another lock.
///
/// If this file handle/descriptor, or a clone of it, already holds an advisory lock, the exact
/// behavior is unspecified and platform dependent, including the possibility that it will
/// deadlock. However, if this method returns `Ok(true)`, then it has acquired an exclusive
/// lock.
/// If this file handle/descriptor, or a clone of it, already holds an lock, the exact behavior
/// is unspecified and platform dependent, including the possibility that it will deadlock.
/// However, if this method returns `Ok(true)`, then it has acquired an exclusive lock.
///
/// If the file not open for writing, it is unspecified whether this function returns an error.
///
/// Note, this is an advisory lock meant to interact with [`lock`], [`lock_shared`],
/// [`try_lock_shared`], and [`unlock`]. Its interactions with other methods, such as [`read`]
/// and [`write`] are platform specific, and it may or may not cause non-lockholders to block.
/// This lock may be advisory or mandatory. This lock is meant to interact with [`lock`],
/// [`try_lock`], [`lock_shared`], [`try_lock_shared`], and [`unlock`]. Its interactions with
/// other methods, such as [`read`] and [`write`] are platform specific, and it may or may not
/// cause non-lockholders to block.
///
/// The lock will be released when this file (along with any other file descriptors/handles
/// duplicated or inherited from it) is closed, or if the [`unlock`] method is called.
@ -755,6 +757,7 @@ impl File {
///
/// [`lock`]: File::lock
/// [`lock_shared`]: File::lock_shared
/// [`try_lock`]: File::try_lock
/// [`try_lock_shared`]: File::try_lock_shared
/// [`unlock`]: File::unlock
/// [`read`]: Read::read
@ -777,21 +780,22 @@ impl File {
self.inner.try_lock()
}
/// Try to acquire a shared (non-exclusive) advisory lock on the file.
/// Try to acquire a shared (non-exclusive) lock on the file.
///
/// Returns `Ok(false)` if an exclusive lock is already held on this file (via another
/// handle/descriptor).
///
/// This acquires a shared advisory lock; more than one file handle may hold a shared lock, but
/// none may hold an exclusive lock at the same time.
/// This acquires a shared lock; more than one file handle may hold a shared lock, but none may
/// hold an exclusive lock at the same time.
///
/// If this file handle, or a clone of it, already holds an advisory lock, the exact behavior is
/// If this file handle, or a clone of it, already holds an lock, the exact behavior is
/// unspecified and platform dependent, including the possibility that it will deadlock.
/// However, if this method returns `Ok(true)`, then it has acquired a shared lock.
///
/// Note, this is an advisory lock meant to interact with [`lock`], [`try_lock`],
/// [`try_lock`], and [`unlock`]. Its interactions with other methods, such as [`read`]
/// and [`write`] are platform specific, and it may or may not cause non-lockholders to block.
/// This lock may be advisory or mandatory. This lock is meant to interact with [`lock`],
/// [`try_lock`], [`lock_shared`], [`try_lock_shared`], and [`unlock`]. Its interactions with
/// other methods, such as [`read`] and [`write`] are platform specific, and it may or may not
/// cause non-lockholders to block.
///
/// The lock will be released when this file (along with any other file descriptors/handles
/// duplicated or inherited from it) is closed, or if the [`unlock`] method is called.
@ -808,6 +812,7 @@ impl File {
/// [`lock`]: File::lock
/// [`lock_shared`]: File::lock_shared
/// [`try_lock`]: File::try_lock
/// [`try_lock_shared`]: File::try_lock_shared
/// [`unlock`]: File::unlock
/// [`read`]: Read::read
/// [`write`]: Write::write