1
# Copyright (C) 2005, 2006, 2007, 2008, 2009 Canonical Ltd
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18
"""Locking using OS file locks or file existence.
20
Note: This method of locking is generally deprecated in favour of LockDir, but
21
is used to lock local WorkingTrees, and by some old formats. It's accessed
22
through Transport.lock_read(), etc.
24
This module causes two methods, lock() and unlock() to be defined in
25
any way that works on the current platform.
27
It is not specified whether these locks are reentrant (i.e. can be
28
taken repeatedly by a single process) or whether they exclude
29
different threads in a single process. That reentrancy is provided by
32
This defines two classes: ReadLock and WriteLock, which can be
33
implemented in different ways on different platforms. Both have an
45
from bzrlib.hooks import HookPoint, Hooks
48
class LockHooks(Hooks):
52
self.create_hook(HookPoint('lock_acquired',
53
"Called with a bzrlib.lock.LockResult when a physical lock is "
54
"acquired.", (1, 8), None))
55
self.create_hook(HookPoint('lock_released',
56
"Called with a bzrlib.lock.LockResult when a physical lock is "
57
"released.", (1, 8), None))
58
self.create_hook(HookPoint('lock_broken',
59
"Called with a bzrlib.lock.LockResult when a physical lock is "
60
"broken.", (1, 15), None))
64
"""Base class for locks.
66
:cvar hooks: Hook dictionary for operations on locks.
72
class LockResult(object):
73
"""Result of an operation on a lock; passed to a hook"""
75
def __init__(self, lock_url, details=None):
76
"""Create a lock result for lock with optional details about the lock."""
77
self.lock_url = lock_url
78
self.details = details
80
def __eq__(self, other):
81
return self.lock_url == other.lock_url and self.details == other.details
84
return '%s(%s%s)' % (self.__class__.__name__,
85
self.lock_url, self.details)
95
have_ctypes_win32 = False
96
if sys.platform == 'win32':
99
import win32con, win32file, pywintypes, winerror
106
have_ctypes_win32 = True
111
class _OSLock(object):
117
def _open(self, filename, filemode):
118
self.filename = osutils.realpath(filename)
120
self.f = open(self.filename, filemode)
123
if e.errno in (errno.EACCES, errno.EPERM):
124
raise errors.LockFailed(self.filename, str(e))
125
if e.errno != errno.ENOENT:
128
# maybe this is an old branch (before may 2005)
129
trace.mutter("trying to create missing lock %r", self.filename)
131
self.f = open(self.filename, 'wb+')
135
"""Clear the self.f attribute cleanly."""
142
from warnings import warn
143
warn("lock on %r not released" % self.f)
147
raise NotImplementedError()
154
LOCK_SH = fcntl.LOCK_SH
155
LOCK_NB = fcntl.LOCK_NB
156
lock_EX = fcntl.LOCK_EX
159
class _fcntl_FileLock(_OSLock):
162
fcntl.lockf(self.f, fcntl.LOCK_UN)
166
class _fcntl_WriteLock(_fcntl_FileLock):
170
def __init__(self, filename):
171
super(_fcntl_WriteLock, self).__init__()
172
# Check we can grab a lock before we actually open the file.
173
self.filename = osutils.realpath(filename)
174
if self.filename in _fcntl_WriteLock._open_locks:
176
raise errors.LockContention(self.filename)
178
self._open(self.filename, 'rb+')
179
# reserve a slot for this lock - even if the lockf call fails,
180
# at thisi point unlock() will be called, because self.f is set.
181
# TODO: make this fully threadsafe, if we decide we care.
182
_fcntl_WriteLock._open_locks.add(self.filename)
184
# LOCK_NB will cause IOError to be raised if we can't grab a
186
fcntl.lockf(self.f, fcntl.LOCK_EX | fcntl.LOCK_NB)
188
if e.errno in (errno.EAGAIN, errno.EACCES):
189
# We couldn't grab the lock
191
# we should be more precise about whats a locking
192
# error and whats a random-other error
193
raise errors.LockContention(self.filename, e)
196
_fcntl_WriteLock._open_locks.remove(self.filename)
200
class _fcntl_ReadLock(_fcntl_FileLock):
204
def __init__(self, filename):
205
super(_fcntl_ReadLock, self).__init__()
206
self.filename = osutils.realpath(filename)
207
_fcntl_ReadLock._open_locks.setdefault(self.filename, 0)
208
_fcntl_ReadLock._open_locks[self.filename] += 1
209
self._open(filename, 'rb')
211
# LOCK_NB will cause IOError to be raised if we can't grab a
213
fcntl.lockf(self.f, fcntl.LOCK_SH | fcntl.LOCK_NB)
215
# we should be more precise about whats a locking
216
# error and whats a random-other error
217
raise errors.LockContention(self.filename, e)
220
count = _fcntl_ReadLock._open_locks[self.filename]
222
del _fcntl_ReadLock._open_locks[self.filename]
224
_fcntl_ReadLock._open_locks[self.filename] = count - 1
227
def temporary_write_lock(self):
228
"""Try to grab a write lock on the file.
230
On platforms that support it, this will upgrade to a write lock
231
without unlocking the file.
232
Otherwise, this will release the read lock, and try to acquire a
235
:return: A token which can be used to switch back to a read lock.
237
if self.filename in _fcntl_WriteLock._open_locks:
238
raise AssertionError('file already locked: %r'
241
wlock = _fcntl_TemporaryWriteLock(self)
242
except errors.LockError:
243
# We didn't unlock, so we can just return 'self'
248
class _fcntl_TemporaryWriteLock(_OSLock):
249
"""A token used when grabbing a temporary_write_lock.
251
Call restore_read_lock() when you are done with the write lock.
254
def __init__(self, read_lock):
255
super(_fcntl_TemporaryWriteLock, self).__init__()
256
self._read_lock = read_lock
257
self.filename = read_lock.filename
259
count = _fcntl_ReadLock._open_locks[self.filename]
261
# Something else also has a read-lock, so we cannot grab a
263
raise errors.LockContention(self.filename)
265
if self.filename in _fcntl_WriteLock._open_locks:
266
raise AssertionError('file already locked: %r'
269
# See if we can open the file for writing. Another process might
270
# have a read lock. We don't use self._open() because we don't want
271
# to create the file if it exists. That would have already been
272
# done by _fcntl_ReadLock
274
new_f = open(self.filename, 'rb+')
276
if e.errno in (errno.EACCES, errno.EPERM):
277
raise errors.LockFailed(self.filename, str(e))
280
# LOCK_NB will cause IOError to be raised if we can't grab a
282
fcntl.lockf(new_f, fcntl.LOCK_EX | fcntl.LOCK_NB)
284
# TODO: Raise a more specific error based on the type of error
285
raise errors.LockContention(self.filename, e)
286
_fcntl_WriteLock._open_locks.add(self.filename)
290
def restore_read_lock(self):
291
"""Restore the original ReadLock."""
292
# For fcntl, since we never released the read lock, just release the
293
# write lock, and return the original lock.
294
fcntl.lockf(self.f, fcntl.LOCK_UN)
296
_fcntl_WriteLock._open_locks.remove(self.filename)
297
# Avoid reference cycles
298
read_lock = self._read_lock
299
self._read_lock = None
303
_lock_classes.append(('fcntl', _fcntl_WriteLock, _fcntl_ReadLock))
306
if have_pywin32 and sys.platform == 'win32':
307
LOCK_SH = 0 # the default
308
LOCK_EX = win32con.LOCKFILE_EXCLUSIVE_LOCK
309
LOCK_NB = win32con.LOCKFILE_FAIL_IMMEDIATELY
312
class _w32c_FileLock(_OSLock):
314
def _lock(self, filename, openmode, lockmode):
315
self._open(filename, openmode)
317
self.hfile = msvcrt.get_osfhandle(self.f.fileno())
318
overlapped = pywintypes.OVERLAPPED()
320
win32file.LockFileEx(self.hfile, lockmode, 0, 0x7fff0000,
322
except pywintypes.error, e:
324
if e.args[0] in (winerror.ERROR_LOCK_VIOLATION,):
325
raise errors.LockContention(filename)
326
## import pdb; pdb.set_trace()
330
raise errors.LockContention(filename, e)
333
overlapped = pywintypes.OVERLAPPED()
335
win32file.UnlockFileEx(self.hfile, 0, 0x7fff0000, overlapped)
338
raise errors.LockContention(self.filename, e)
341
class _w32c_ReadLock(_w32c_FileLock):
342
def __init__(self, filename):
343
super(_w32c_ReadLock, self).__init__()
344
self._lock(filename, 'rb', LOCK_SH + LOCK_NB)
346
def temporary_write_lock(self):
347
"""Try to grab a write lock on the file.
349
On platforms that support it, this will upgrade to a write lock
350
without unlocking the file.
351
Otherwise, this will release the read lock, and try to acquire a
354
:return: A token which can be used to switch back to a read lock.
356
# I can't find a way to upgrade a read lock to a write lock without
357
# unlocking first. So here, we do just that.
360
wlock = _w32c_WriteLock(self.filename)
361
except errors.LockError:
362
return False, _w32c_ReadLock(self.filename)
366
class _w32c_WriteLock(_w32c_FileLock):
367
def __init__(self, filename):
368
super(_w32c_WriteLock, self).__init__()
369
self._lock(filename, 'rb+', LOCK_EX + LOCK_NB)
371
def restore_read_lock(self):
372
"""Restore the original ReadLock."""
373
# For win32 we had to completely let go of the original lock, so we
374
# just unlock and create a new read lock.
376
return _w32c_ReadLock(self.filename)
379
_lock_classes.append(('pywin32', _w32c_WriteLock, _w32c_ReadLock))
382
if have_ctypes_win32:
383
# These constants were copied from the win32con.py module.
384
LOCKFILE_FAIL_IMMEDIATELY = 1
385
LOCKFILE_EXCLUSIVE_LOCK = 2
386
# Constant taken from winerror.py module
387
ERROR_LOCK_VIOLATION = 33
390
LOCK_EX = LOCKFILE_EXCLUSIVE_LOCK
391
LOCK_NB = LOCKFILE_FAIL_IMMEDIATELY
392
_LockFileEx = ctypes.windll.kernel32.LockFileEx
393
_UnlockFileEx = ctypes.windll.kernel32.UnlockFileEx
394
_GetLastError = ctypes.windll.kernel32.GetLastError
396
### Define the OVERLAPPED structure.
397
# http://msdn2.microsoft.com/en-us/library/ms684342.aspx
398
# typedef struct _OVERLAPPED {
399
# ULONG_PTR Internal;
400
# ULONG_PTR InternalHigh;
411
class _inner_struct(ctypes.Structure):
412
_fields_ = [('Offset', ctypes.c_uint), # DWORD
413
('OffsetHigh', ctypes.c_uint), # DWORD
416
class _inner_union(ctypes.Union):
417
_fields_ = [('anon_struct', _inner_struct), # struct
418
('Pointer', ctypes.c_void_p), # PVOID
421
class OVERLAPPED(ctypes.Structure):
422
_fields_ = [('Internal', ctypes.c_void_p), # ULONG_PTR
423
('InternalHigh', ctypes.c_void_p), # ULONG_PTR
424
('_inner_union', _inner_union),
425
('hEvent', ctypes.c_void_p), # HANDLE
428
class _ctypes_FileLock(_OSLock):
430
def _lock(self, filename, openmode, lockmode):
431
self._open(filename, openmode)
433
self.hfile = msvcrt.get_osfhandle(self.f.fileno())
434
overlapped = OVERLAPPED()
435
result = _LockFileEx(self.hfile, # HANDLE hFile
436
lockmode, # DWORD dwFlags
437
0, # DWORD dwReserved
438
0x7fffffff, # DWORD nNumberOfBytesToLockLow
439
0x00000000, # DWORD nNumberOfBytesToLockHigh
440
ctypes.byref(overlapped), # lpOverlapped
444
last_err = _GetLastError()
445
if last_err in (ERROR_LOCK_VIOLATION,):
446
raise errors.LockContention(filename)
447
raise errors.LockContention(filename,
448
'Unknown locking error: %s' % (last_err,))
451
overlapped = OVERLAPPED()
452
result = _UnlockFileEx(self.hfile, # HANDLE hFile
453
0, # DWORD dwReserved
454
0x7fffffff, # DWORD nNumberOfBytesToLockLow
455
0x00000000, # DWORD nNumberOfBytesToLockHigh
456
ctypes.byref(overlapped), # lpOverlapped
461
last_err = _GetLastError()
462
raise errors.LockContention(self.filename,
463
'Unknown unlocking error: %s' % (last_err,))
466
class _ctypes_ReadLock(_ctypes_FileLock):
467
def __init__(self, filename):
468
super(_ctypes_ReadLock, self).__init__()
469
self._lock(filename, 'rb', LOCK_SH + LOCK_NB)
471
def temporary_write_lock(self):
472
"""Try to grab a write lock on the file.
474
On platforms that support it, this will upgrade to a write lock
475
without unlocking the file.
476
Otherwise, this will release the read lock, and try to acquire a
479
:return: A token which can be used to switch back to a read lock.
481
# I can't find a way to upgrade a read lock to a write lock without
482
# unlocking first. So here, we do just that.
485
wlock = _ctypes_WriteLock(self.filename)
486
except errors.LockError:
487
return False, _ctypes_ReadLock(self.filename)
490
class _ctypes_WriteLock(_ctypes_FileLock):
491
def __init__(self, filename):
492
super(_ctypes_WriteLock, self).__init__()
493
self._lock(filename, 'rb+', LOCK_EX + LOCK_NB)
495
def restore_read_lock(self):
496
"""Restore the original ReadLock."""
497
# For win32 we had to completely let go of the original lock, so we
498
# just unlock and create a new read lock.
500
return _ctypes_ReadLock(self.filename)
503
_lock_classes.append(('ctypes', _ctypes_WriteLock, _ctypes_ReadLock))
506
if len(_lock_classes) == 0:
507
raise NotImplementedError(
508
"We must have one of fcntl, pywin32, or ctypes available"
509
" to support OS locking."
513
# We default to using the first available lock class.
514
_lock_type, WriteLock, ReadLock = _lock_classes[0]