Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/filelock/_unix.py: 46%

1from __future__ import annotations 

2 

3__lazy_modules__ = ["contextlib", "filelock._util", "pathlib", "warnings"] 

4 

5import os 

6import sys 

7import warnings 

8from contextlib import suppress 

9from errno import EACCES, EAGAIN, ENOSYS, EWOULDBLOCK 

10from pathlib import Path 

11from typing import Final, NamedTuple, cast 

12 

13from filelock._api import BaseFileLock 

14from filelock._util import remove_own_file 

15 

16has_fcntl = False 

17if sys.platform == "win32": # pragma: win32 cover 

18 

19 class UnixFileLock(BaseFileLock): 

20 """Uses the :func:`fcntl.flock` to hard lock the lock file on unix systems.""" 

21 

22 def _acquire(self) -> None: 

23 raise NotImplementedError 

24 

25 def _release(self) -> None: 

26 raise NotImplementedError 

27 

28else: # pragma: win32 no cover 

29 try: 

30 import fcntl 

31 

32 _ = (fcntl.flock, fcntl.LOCK_EX, fcntl.LOCK_NB, fcntl.LOCK_UN) 

33 except (ImportError, AttributeError): 

34 _FCNTL_UNAVAILABLE: Final[str] = "fcntl is unavailable" 

35 

36 def _lock_fd_nonblocking(_fd: int) -> bool: 

37 raise OSError(ENOSYS, _FCNTL_UNAVAILABLE) 

38 

39 def _unlock_fd(_fd: int) -> None: 

40 raise OSError(ENOSYS, _FCNTL_UNAVAILABLE) 

41 

42 else: 

43 has_fcntl = True 

44 # Contention errnos for a nonblocking flock. EAGAIN/EWOULDBLOCK are the usual "held elsewhere" codes; some 

45 # filesystems report EACCES instead, so treat it as contention too rather than a permanent error. 

46 _CONTENTION_ERRNOS: Final[frozenset[int]] = frozenset({EACCES, EAGAIN, EWOULDBLOCK}) 

47 

48 def _lock_fd_nonblocking(fd: int) -> bool: 

49 # One nonblocking exclusive flock attempt shared by UnixFileLock and lock_descriptor, so both contend on 

50 # the same lock and classify errors identically. The caller owns fd; this never closes it. 

51 try: 

52 fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB) 

53 except OSError as exception: 

54 if exception.errno in _CONTENTION_ERRNOS: 

55 return False 

56 raise 

57 return True 

58 

59 def _unlock_fd(fd: int) -> None: 

60 fcntl.flock(fd, fcntl.LOCK_UN) 

61 

62 def _flock_is_missing(fd: int) -> bool: 

63 try: 

64 _lock_fd_nonblocking(fd) 

65 except OSError as exception: 

66 return exception.errno == ENOSYS 

67 return False # a flock the probe won is released when the caller closes fd 

68 

69 class _MissingFlock(NamedTuple): 

70 fd: int 

71 exception: OSError 

72 created: bool 

73 

74 class UnixFileLock(BaseFileLock): 

75 """ 

76 Uses the :func:`fcntl.flock` to hard lock the lock file on unix systems. 

77 

78 We leave the lock file in place after release. Unlinking a locked file on Unix splits 

79 waiters across inodes and breaks mutual exclusion for processes that coordinate via the 

80 same path. 

81 """ 

82 

83 def _acquire(self) -> None: 

84 if (missing_flock := self._acquire_native()) is not None: 

85 fd, exception, created = missing_flock 

86 self._switch_to_soft_lock(fd, exception, created=created) 

87 

88 def _acquire_native(self) -> _MissingFlock | None: 

89 if (opened := self._open_lock_file()) is None: 

90 return None 

91 fd, created = opened 

92 self._mark_descriptor_pending(fd) 

93 if created: 

94 # Before the flock: a peer may win it first, and only the creator may set the mode. Outside the flock 

95 # handler below: an fchmod that answers ENOSYS says nothing about flock. 

96 try: 

97 self._apply_explicit_mode(fd) 

98 except BaseException: 

99 self._mark_descriptor_released() 

100 os.close(fd) 

101 raise 

102 # One guard covers the flock through the recording of the hold. A signal handler that raises in between 

103 # would otherwise leave an unreferenced descriptor, and its flock, open until the process exits. 

104 locked = False 

105 try: 

106 locked = _lock_fd_nonblocking(fd) 

107 if locked and self._finalize_locked_fd(fd): 

108 return None 

109 except BaseException as exception: 

110 if not locked and isinstance(exception, OSError) and exception.errno == ENOSYS: 

111 return _MissingFlock(fd, exception, created) 

112 # Contention returns False from _lock_fd_nonblocking, so a raise here is a failure. 

113 self._mark_descriptor_released() 

114 os.close(fd) 

115 raise 

116 self._mark_descriptor_released() 

117 os.close(fd) # contention or an unlinked inode; let the retry loop try again 

118 return None 

119 

120 def _open_lock_file(self) -> tuple[int, bool] | None: 

121 # No O_TRUNC: a contender that loses the flock must not truncate the holder's file (#591), and neither may 

122 # the winner, since a file renamed or hard-linked to the lock path is indistinguishable from a lock file. 

123 # O_EXCL tells whether this attempt created the inode: only then does it get the explicit mode, and the 

124 # ENOSYS fallback removes only its own placeholder. O_NONBLOCK: a lease (Linux F_SETLEASE) on the file would 

125 # otherwise block the open for up to fs.lease-break-time, beyond timeout, blocking=False and cancel_check. 

126 open_flags = os.O_RDWR | os.O_NONBLOCK 

127 if (o_nofollow := getattr(os, "O_NOFOLLOW", None)) is not None: 

128 open_flags |= o_nofollow 

129 open_mode = self._open_mode() 

130 try: 

131 return os.open(self._lock_path, open_flags | os.O_CREAT | os.O_EXCL, open_mode), True 

132 except FileExistsError: 

133 pass 

134 except FileNotFoundError: 

135 # On FUSE/NFS a split LOOKUP + CREATE lets a concurrent unlink() race the create, so ENOENT is transient 

136 # contention. An empty or separator-terminated path (Path() strips the separator) fails this way on 

137 # every attempt on macOS, so re-raise rather than retry forever. 

138 if self._lock_path and not self._lock_path.endswith(os.sep) and Path(self._lock_path).parent.exists(): 

139 return None 

140 raise 

141 except PermissionError: 

142 # Sticky-bit dirs (e.g. /tmp): O_CREAT fails if another user owns the file (#317). 

143 if not Path(self._lock_path).exists(): 

144 raise 

145 return self._open_existing_lock_file(open_flags, open_mode) 

146 

147 def _open_existing_lock_file(self, open_flags: int, open_mode: int) -> tuple[int, bool] | None: 

148 try: 

149 return os.open(self._lock_path, open_flags, open_mode), False 

150 except FileNotFoundError: 

151 return None # unlinked since the create attempt; let the retry loop start over 

152 except BlockingIOError: 

153 return None # a lease is breaking: contention, so the retry loop keeps the deadline 

154 except PermissionError: 

155 # A marker another account left is readable but not writable. Without flock, waiting on it only needs 

156 # reading it; with flock the lock writes its file, so the denial stands. 

157 try: 

158 fd = os.open(self._lock_path, open_flags & ~os.O_RDWR | os.O_RDONLY) 

159 except (FileNotFoundError, BlockingIOError): 

160 return None # unlinked, or leased: the kernel checks permission before the lease 

161 if _flock_is_missing(fd): 

162 return fd, False 

163 os.close(fd) 

164 raise 

165 

166 def _apply_explicit_mode(self, fd: int) -> None: 

167 if self.has_explicit_mode: 

168 with suppress(PermissionError): 

169 os.fchmod(fd, self._context.mode) 

170 

171 def _finalize_locked_fd(self, fd: int) -> bool: 

172 # Runs with the flock held; the caller closes fd on failure. A concurrent _release() may have unlinked 

173 # the file between our open() and flock(), which st_nlink 0 shows. That lock guards no name, so report 

174 # it and let the retry loop start over. 

175 if (stat_result := os.fstat(fd)).st_nlink == 0: 

176 return False 

177 self._mark_descriptor_owned(fd, (stat_result.st_dev, stat_result.st_ino)) 

178 return True 

179 

180 def _switch_to_soft_lock(self, fd: int, missing_flock: OSError, *, created: bool) -> None: 

181 # The filesystem does not implement flock. Fail closed when the caller opted out of existence-lock 

182 # semantics (#603), asked to preserve the pathname (#605), or set an on_acquired hook (#607), none of which 

183 # a soft lock can honor. 

184 falls_back: Final = self._fallback_to_soft and not self._preserve_lock_file and self._on_acquired is None 

185 try: 

186 # A file this attempt did not create may be a peer's live marker, so it stays. Our own placeholder goes 

187 # before the close: the open descriptor keeps its inode number from a peer's marker, and an exchange 

188 # puts back a peer's marker that replaced it. 

189 if created and falls_back: 

190 with suppress(OSError): 

191 remove_own_file(self._lock_path, fd) 

192 finally: 

193 self._mark_descriptor_released() 

194 os.close(fd) 

195 if not falls_back: 

196 raise missing_flock 

197 self._fallback_to_soft_lock() 

198 self._acquire() 

199 

200 def _fallback_to_soft_lock(self: BaseFileLock) -> None: 

201 # Import lazily: this runs only on the rare flock fallback, and asyncio imports _unix, so a 

202 # module-level import of it here would cycle. 

203 from filelock._soft import SoftFileLock # ruff:ignore[import-outside-top-level] 

204 

205 warnings.warn("flock not supported on this filesystem, falling back to SoftFileLock", stacklevel=2) 

206 from filelock.asyncio import AsyncSoftFileLock, BaseAsyncFileLock # ruff:ignore[import-outside-top-level] # asyncio imports this module 

207 

208 self.__class__ = AsyncSoftFileLock if isinstance(self, BaseAsyncFileLock) else SoftFileLock 

209 

210 def _release(self) -> None: 

211 fd = cast("int", self._context.lock_file_fd) 

212 # Retain the descriptor until flock succeeds: a failed unlock leaves the kernel lock held, so is_locked 

213 # must keep reporting held for a retry. Once flock commits, clear held state and close as post-unlock 

214 # cleanup; a close failure (EIO on FUSE/Docker bind mounts) does not make the kernel lock held again. 

215 _unlock_fd(fd) 

216 self._mark_descriptor_released() 

217 self._close_released_fd(fd, default_suppresses=True) 

218 

219 

220if sys.platform == "win32": # pragma: win32 cover 

221 __all__ = ["UnixFileLock", "has_fcntl"] 

222else: # pragma: win32 no cover 

223 __all__ = ["UnixFileLock", "_lock_fd_nonblocking", "_unlock_fd", "has_fcntl"]