Mirrors/rust
1
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2026-05-29 12:36:35 +03:00
Code Issues Packages Projects Releases Wiki Activity

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
library/std/src/fs.rs
+40 -35
View File
@@ -624,20 +624,20 @@ pub fn sync_data(&self) -> io::Result<()> {
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 @@ pub fn sync_data(&self) -> io::Result<()> {
///
/// [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 @@ pub fn lock(&self) -> io::Result<()> {
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 @@ pub fn lock(&self) -> io::Result<()> {
/// [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 @@ pub fn lock_shared(&self) -> io::Result<()> {
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 @@ pub fn lock_shared(&self) -> io::Result<()> {
///
/// [`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 @@ pub fn try_lock(&self) -> io::Result<bool> {
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 @@ pub fn try_lock(&self) -> io::Result<bool> {
/// [`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