authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2021-06-29 14:15:44-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2021-06-29 14:25:04-07:00
loge32530b6a31432e43cc4d4d793796007423f2edb
treed646900dc75b5863b776d117dd43e6c8005130dc
parent06129d7e3d5a8d9449edc98510a6d4f7a171b27f

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+36-14
...@@ -74,17 +74,28 @@ pub const File = struct {...@@ -74,17 +74,28 @@ pub const File = struct {
74 read: bool = true,74 read: bool = true,
75 write: bool = false,75 write: bool = false,
7676
77 /// Open the file with a lock to prevent other processes from accessing it at the77 /// Open the file with an advisory lock to coordinate with other processes
78 /// same time. An exclusive lock will prevent other processes from acquiring a lock.78 /// accessing it at the same time. An exclusive lock will prevent other
79 /// A shared lock will prevent other processes from acquiring a exclusive lock, but79 /// processes from acquiring a lock. A shared lock will prevent other
80 /// doesn't prevent other process from getting their own shared locks.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 /// This means that a process that does not respect the locking API can still get access84 /// This means that a process that does not respect the locking API can still get access
84 /// to the file, despite the lock.85 /// to the file, despite the lock.
85 ///86 ///
86 /// Windows' file locks are mandatory, and any process attempting to access the file will87 /// On these operating systems, the lock is acquired atomically with
87 /// receive an error.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 /// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt100 /// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
90 lock: Lock = .None,101 lock: Lock = .None,
...@@ -120,17 +131,28 @@ pub const File = struct {...@@ -120,17 +131,28 @@ pub const File = struct {
120 /// `error.PathAlreadyExists` to be returned.131 /// `error.PathAlreadyExists` to be returned.
121 exclusive: bool = false,132 exclusive: bool = false,
122133
123 /// Open the file with a lock to prevent other processes from accessing it at the134 /// Open the file with an advisory lock to coordinate with other processes
124 /// same time. An exclusive lock will prevent other processes from acquiring a lock.135 /// accessing it at the same time. An exclusive lock will prevent other
125 /// A shared lock will prevent other processes from acquiring a exclusive lock, but136 /// processes from acquiring a lock. A shared lock will prevent other
126 /// doesn't prevent other process from getting their own shared locks.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 /// This means that a process that does not respect the locking API can still get access141 /// This means that a process that does not respect the locking API can still get access
130 /// to the file, despite the lock.142 /// to the file, despite the lock.
131 ///143 ///
132 /// Windows's file locks are mandatory, and any process attempting to access the file will144 /// On these operating systems, the lock is acquired atomically with
133 /// receive an error.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 /// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt157 /// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
136 lock: Lock = .None,158 lock: Lock = .None,