commit e32530b6a31432e43cc4d4d793796007423f2edb (tree)
parent 06129d7e3d5a8d9449edc98510a6d4f7a171b27f
Author: Andrew Kelley <andrew@ziglang.org>
Date: Tue, 29 Jun 2021 14:15:44 -0700
std.fs.File: update doc comments regarding locking
Update to accomodate the differences in Windows, which is now advisory
file locking, and include details about which operating systems have
atomic locking flags.
Diffstat:
1 file changed, 36 insertions(+), 14 deletions(-)
diff --git a/lib/std/fs/file.zig b/lib/std/fs/file.zig
@@ -74,17 +74,28 @@ pub const File = struct {
read: bool = true,
write: bool = false,
- /// Open the file with a lock to prevent other processes from accessing it at the
- /// same time. An exclusive lock will prevent other processes from acquiring a lock.
- /// A shared lock will prevent other processes from acquiring a exclusive lock, but
- /// doesn't prevent other process from getting their own shared locks.
+ /// Open the file with an advisory lock to coordinate with other processes
+ /// accessing it at the same time. An exclusive lock will prevent other
+ /// processes from acquiring a lock. A shared lock will prevent other
+ /// processes from acquiring a exclusive lock, but does not prevent
+ /// other process from getting their own shared locks.
///
- /// Note that the lock is only advisory on Linux, except in very specific cirsumstances[1].
+ /// The lock is advisory, except on Linux in very specific cirsumstances[1].
/// This means that a process that does not respect the locking API can still get access
/// to the file, despite the lock.
///
- /// Windows' file locks are mandatory, and any process attempting to access the file will
- /// receive an error.
+ /// On these operating systems, the lock is acquired atomically with
+ /// opening the file:
+ /// * Darwin
+ /// * DragonFlyBSD
+ /// * FreeBSD
+ /// * Haiku
+ /// * NetBSD
+ /// * OpenBSD
+ /// On these operating systems, the lock is acquired via a separate syscall
+ /// after opening the file:
+ /// * Linux
+ /// * Windows
///
/// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
lock: Lock = .None,
@@ -120,17 +131,28 @@ pub const File = struct {
/// `error.PathAlreadyExists` to be returned.
exclusive: bool = false,
- /// Open the file with a lock to prevent other processes from accessing it at the
- /// same time. An exclusive lock will prevent other processes from acquiring a lock.
- /// A shared lock will prevent other processes from acquiring a exclusive lock, but
- /// doesn't prevent other process from getting their own shared locks.
+ /// Open the file with an advisory lock to coordinate with other processes
+ /// accessing it at the same time. An exclusive lock will prevent other
+ /// processes from acquiring a lock. A shared lock will prevent other
+ /// processes from acquiring a exclusive lock, but does not prevent
+ /// other process from getting their own shared locks.
///
- /// Note that the lock is only advisory on Linux, except in very specific cirsumstances[1].
+ /// The lock is advisory, except on Linux in very specific cirsumstances[1].
/// This means that a process that does not respect the locking API can still get access
/// to the file, despite the lock.
///
- /// Windows's file locks are mandatory, and any process attempting to access the file will
- /// receive an error.
+ /// On these operating systems, the lock is acquired atomically with
+ /// opening the file:
+ /// * Darwin
+ /// * DragonFlyBSD
+ /// * FreeBSD
+ /// * Haiku
+ /// * NetBSD
+ /// * OpenBSD
+ /// On these operating systems, the lock is acquired via a separate syscall
+ /// after opening the file:
+ /// * Linux
+ /// * Windows
///
/// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
lock: Lock = .None,
