Commit e32530b6a31432e43cc4d4d793796007423f2edb | zig

author	Andrew Kelley <andrew@ziglang.org> 2021-06-29 14:15:44-07:00
committer	Andrew Kelley <andrew@ziglang.org> 2021-06-29 14:25:04-07:00
log	e32530b6a31432e43cc4d4d793796007423f2edb
tree	d646900dc75b5863b776d117dd43e6c8005130dc
parent	06129d7e3d5a8d9449edc98510a6d4f7a171b27f

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.

1 files changed, 36 insertions(+), 14 deletions(-)

lib
- std
  - fs
    file.zig

lib/std/fs/file.zig+36-14

...	...	@@ -74,17 +74,28 @@ pub const File = struct {
74	74	read: bool = true,
75	75	write: bool = false,
76	76
77		/// Open the file with a lock to prevent other processes from accessing it at the
78		/// same time. An exclusive lock will prevent other processes from acquiring a lock.
79		/// A shared lock will prevent other processes from acquiring a exclusive lock, but
80		/// doesn't prevent other process from getting their own shared locks.
	77	/// Open the file with an advisory lock to coordinate with other processes
	78	/// accessing it at the same time. An exclusive lock will prevent other
	79	/// processes from acquiring a lock. A shared lock will prevent other
	80	/// processes from acquiring a exclusive lock, but does not prevent
	81	/// other process from getting their own shared locks.
81	82	///
82		/// Note that the lock is only advisory on Linux, except in very specific cirsumstances[1].
	83	/// The lock is advisory, except on Linux in very specific cirsumstances[1].
83	84	/// This means that a process that does not respect the locking API can still get access
84	85	/// to the file, despite the lock.
85	86	///
86		/// Windows' file locks are mandatory, and any process attempting to access the file will
87		/// receive an error.
	87	/// On these operating systems, the lock is acquired atomically with
	88	/// opening the file:
	89	/// * Darwin
	90	/// * DragonFlyBSD
	91	/// * FreeBSD
	92	/// * Haiku
	93	/// * NetBSD
	94	/// * OpenBSD
	95	/// On these operating systems, the lock is acquired via a separate syscall
	96	/// after opening the file:
	97	/// * Linux
	98	/// * Windows
88	99	///
89	100	/// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
90	101	lock: Lock = .None,
...	...	@@ -120,17 +131,28 @@ pub const File = struct {
120	131	/// `error.PathAlreadyExists` to be returned.
121	132	exclusive: bool = false,
122	133
123		/// Open the file with a lock to prevent other processes from accessing it at the
124		/// same time. An exclusive lock will prevent other processes from acquiring a lock.
125		/// A shared lock will prevent other processes from acquiring a exclusive lock, but
126		/// doesn't prevent other process from getting their own shared locks.
	134	/// Open the file with an advisory lock to coordinate with other processes
	135	/// accessing it at the same time. An exclusive lock will prevent other
	136	/// processes from acquiring a lock. A shared lock will prevent other
	137	/// processes from acquiring a exclusive lock, but does not prevent
	138	/// other process from getting their own shared locks.
127	139	///
128		/// Note that the lock is only advisory on Linux, except in very specific cirsumstances[1].
	140	/// The lock is advisory, except on Linux in very specific cirsumstances[1].
129	141	/// This means that a process that does not respect the locking API can still get access
130	142	/// to the file, despite the lock.
131	143	///
132		/// Windows's file locks are mandatory, and any process attempting to access the file will
133		/// receive an error.
	144	/// On these operating systems, the lock is acquired atomically with
	145	/// opening the file:
	146	/// * Darwin
	147	/// * DragonFlyBSD
	148	/// * FreeBSD
	149	/// * Haiku
	150	/// * NetBSD
	151	/// * OpenBSD
	152	/// On these operating systems, the lock is acquired via a separate syscall
	153	/// after opening the file:
	154	/// * Linux
	155	/// * Windows
134	156	///
135	157	/// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
136	158	lock: Lock = .None,