~bzr-pqm/bzr/bzr.dev

1553.5.12 by Martin Pool
New LockDir locking mechanism
1
# Copyright (C) 2006 Canonical Ltd
1887.1.1 by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines,
2
#
1553.5.12 by Martin Pool
New LockDir locking mechanism
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.
1887.1.1 by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines,
7
#
1553.5.12 by Martin Pool
New LockDir locking mechanism
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.
1887.1.1 by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines,
12
#
1553.5.12 by Martin Pool
New LockDir locking mechanism
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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
1553.5.31 by Martin Pool
LockDir doc corrections
17
"""On-disk mutex protecting a resource
1553.5.12 by Martin Pool
New LockDir locking mechanism
18
1553.5.33 by Martin Pool
LockDir review comment fixes
19
bzr on-disk objects are locked by the existence of a directory with a
20
particular name within the control directory.  We use this rather than OS
21
internal locks (such as flock etc) because they can be seen across all
22
transports, including http.
1553.5.12 by Martin Pool
New LockDir locking mechanism
23
24
Objects can be read if there is only physical read access; therefore 
25
readers can never be required to create a lock, though they will
26
check whether a writer is using the lock.  Writers can't detect
27
whether anyone else is reading from the resource as they write.
28
This works because of ordering constraints that make sure readers
29
see a consistent view of existing data.
30
31
Waiting for a lock must be done by polling; this can be aborted after
32
a timeout.
33
34
Locks must always be explicitly released, typically from a try/finally
35
block -- they are not released from a finalizer or when Python
36
exits.
37
38
Locks may fail to be released if the process is abruptly terminated
39
(machine stop, SIGKILL) or if a remote transport becomes permanently
40
disconnected.  There is therefore a method to break an existing lock.
41
This should rarely be used, and generally only with user approval.
42
Locks contain some information on when the lock was taken and by who
43
which may guide in deciding whether it can safely be broken.  (This is
44
similar to the messages displayed by emacs and vim.) Note that if the
45
lock holder is still alive they will get no notification that the lock
46
has been broken and will continue their work -- so it is important to be
47
sure they are actually dead.
48
49
A lock is represented on disk by a directory of a particular name,
50
containing an information file.  Taking a lock is done by renaming a
51
temporary directory into place.  We use temporary directories because
52
for all known transports and filesystems we believe that exactly one
53
attempt to claim the lock will succeed and the others will fail.  (Files
54
won't do because some filesystems or transports only have
55
rename-and-overwrite, making it hard to tell who won.)
56
57
The desired characteristics are:
58
59
* Locks are not reentrant.  (That is, a client that tries to take a 
60
  lock it already holds may deadlock or fail.)
61
* Stale locks can be guessed at by a heuristic
62
* Lost locks can be broken by any client
63
* Failed lock operations leave little or no mess
64
* Deadlocks are avoided by having a timeout always in use, clients
65
  desiring indefinite waits can retry or set a silly big timeout.
66
67
Storage formats use the locks, and also need to consider concurrency
68
issues underneath the lock.  A format may choose not to use a lock
69
at all for some operations.
70
71
LockDirs always operate over a Transport.  The transport may be readonly, in
72
which case the lock can be queried but not acquired.
73
74
Locks are identified by a path name, relative to a base transport.
75
76
Calling code will typically want to make sure there is exactly one LockDir
77
object per actual lock on disk.  This module does nothing to prevent aliasing
78
and deadlocks will likely occur if the locks are aliased.
79
80
In the future we may add a "freshen" method which can be called
81
by a lock holder to check that their lock has not been broken, and to 
82
update the timestamp within it.
83
1553.5.18 by Martin Pool
LockDir should use Transport.rename when releasing locks too.
84
Example usage:
85
86
>>> from bzrlib.transport.memory import MemoryTransport
87
>>> # typically will be obtained from a BzrDir, Branch, etc
88
>>> t = MemoryTransport()
89
>>> l = LockDir(t, 'sample-lock')
1553.5.61 by Martin Pool
Locks protecting LockableFiles must now be explicitly created before use.
90
>>> l.create()
1553.5.18 by Martin Pool
LockDir should use Transport.rename when releasing locks too.
91
>>> l.wait_lock()
92
>>> # do something here
93
>>> l.unlock()
94
1553.5.12 by Martin Pool
New LockDir locking mechanism
95
"""
96
97
import os
98
import time
99
from StringIO import StringIO
100
101
import bzrlib.config
102
from bzrlib.errors import (
103
        DirectoryNotEmpty,
104
        FileExists,
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
105
        LockBreakMismatch,
1553.5.23 by Martin Pool
Start LockDir.confirm method and LockBroken exception
106
        LockBroken,
1553.5.12 by Martin Pool
New LockDir locking mechanism
107
        LockContention,
108
        LockNotHeld,
109
        NoSuchFile,
1662.1.12 by Martin Pool
Translate unknown sftp errors to PathError, no NoSuchFile
110
        PathError,
1558.10.1 by Aaron Bentley
Handle lockdirs over NFS properly
111
        ResourceBusy,
1553.5.12 by Martin Pool
New LockDir locking mechanism
112
        UnlockableTransport,
113
        )
1662.1.12 by Martin Pool
Translate unknown sftp errors to PathError, no NoSuchFile
114
from bzrlib.trace import mutter
1553.5.12 by Martin Pool
New LockDir locking mechanism
115
from bzrlib.transport import Transport
116
from bzrlib.osutils import rand_chars
1993.1.2 by John Arbash Meinel
Use Stanza.to_string() rather than a RioWriter
117
from bzrlib.rio import read_stanza, Stanza
1553.5.12 by Martin Pool
New LockDir locking mechanism
118
119
# XXX: At the moment there is no consideration of thread safety on LockDir
120
# objects.  This should perhaps be updated - e.g. if two threads try to take a
121
# lock at the same time they should *both* get it.  But then that's unlikely
122
# to be a good idea.
123
124
# TODO: Perhaps store some kind of note like the bzr command line in the lock
125
# info?
126
127
# TODO: Some kind of callback run while polling a lock to show progress
128
# indicators.
129
1553.5.59 by Martin Pool
Pass file/mode bits through to creation of lock files/dirs
130
# TODO: Make sure to pass the right file and directory mode bits to all
131
# files/dirs created.
132
1553.5.21 by Martin Pool
Put default LockDir timeouts in variables; increase timeout to 3min
133
_DEFAULT_TIMEOUT_SECONDS = 300
134
_DEFAULT_POLL_SECONDS = 0.5
1553.5.12 by Martin Pool
New LockDir locking mechanism
135
136
class LockDir(object):
1553.5.33 by Martin Pool
LockDir review comment fixes
137
    """Write-lock guarding access to data."""
1553.5.12 by Martin Pool
New LockDir locking mechanism
138
1553.5.33 by Martin Pool
LockDir review comment fixes
139
    __INFO_NAME = '/info'
1553.5.12 by Martin Pool
New LockDir locking mechanism
140
1553.5.59 by Martin Pool
Pass file/mode bits through to creation of lock files/dirs
141
    def __init__(self, transport, path, file_modebits=0644, dir_modebits=0755):
1553.5.12 by Martin Pool
New LockDir locking mechanism
142
        """Create a new LockDir object.
143
144
        The LockDir is initially unlocked - this just creates the object.
145
146
        :param transport: Transport which will contain the lock
147
148
        :param path: Path to the lock within the base directory of the 
149
            transport.
150
        """
151
        assert isinstance(transport, Transport), \
152
            ("not a transport: %r" % transport)
153
        self.transport = transport
154
        self.path = path
155
        self._lock_held = False
1553.5.54 by Martin Pool
Add LockDir.read_lock fake method
156
        self._fake_read_lock = False
1553.5.58 by Martin Pool
Change LockDirs to format "lock-name/held/info"
157
        self._held_dir = path + '/held'
158
        self._held_info_path = self._held_dir + self.__INFO_NAME
1553.5.59 by Martin Pool
Pass file/mode bits through to creation of lock files/dirs
159
        self._file_modebits = file_modebits
160
        self._dir_modebits = dir_modebits
1553.5.12 by Martin Pool
New LockDir locking mechanism
161
        self.nonce = rand_chars(20)
162
163
    def __repr__(self):
164
        return '%s(%s%s)' % (self.__class__.__name__,
165
                             self.transport.base,
166
                             self.path)
167
1553.5.13 by Martin Pool
New Transport.rename that mustn't overwrite
168
    is_held = property(lambda self: self._lock_held)
1553.5.12 by Martin Pool
New LockDir locking mechanism
169
1666.1.4 by Robert Collins
* 'Metadir' is now the default disk format. This improves behaviour in
170
    def create(self, mode=None):
1553.5.58 by Martin Pool
Change LockDirs to format "lock-name/held/info"
171
        """Create the on-disk lock.
172
173
        This is typically only called when the object/directory containing the 
174
        directory is first created.  The lock is not held when it's created.
175
        """
176
        if self.transport.is_readonly():
177
            raise UnlockableTransport(self.transport)
1666.1.4 by Robert Collins
* 'Metadir' is now the default disk format. This improves behaviour in
178
        self.transport.mkdir(self.path, mode=mode)
1553.5.58 by Martin Pool
Change LockDirs to format "lock-name/held/info"
179
1553.5.12 by Martin Pool
New LockDir locking mechanism
180
    def attempt_lock(self):
1553.5.33 by Martin Pool
LockDir review comment fixes
181
        """Take the lock; fail if it's already held.
1553.5.12 by Martin Pool
New LockDir locking mechanism
182
        
183
        If you wish to block until the lock can be obtained, call wait_lock()
184
        instead.
185
        """
1553.5.54 by Martin Pool
Add LockDir.read_lock fake method
186
        if self._fake_read_lock:
187
            raise LockContention(self)
1553.5.12 by Martin Pool
New LockDir locking mechanism
188
        if self.transport.is_readonly():
189
            raise UnlockableTransport(self.transport)
190
        try:
1553.5.58 by Martin Pool
Change LockDirs to format "lock-name/held/info"
191
            tmpname = '%s/pending.%s.tmp' % (self.path, rand_chars(20))
1955.1.1 by John Arbash Meinel
LockDir can create the root directory if it fails to create a pending directory due to NoSuchFile.
192
            try:
193
                self.transport.mkdir(tmpname)
194
            except NoSuchFile:
195
                # This may raise a FileExists exception
196
                # which is okay, it will be caught later and determined
197
                # to be a LockContention.
198
                self.create(mode=self._dir_modebits)
199
                
200
                # After creating the lock directory, try again
201
                self.transport.mkdir(tmpname)
202
1993.1.2 by John Arbash Meinel
Use Stanza.to_string() rather than a RioWriter
203
            info_bytes = self._prepare_info()
1993.1.1 by John Arbash Meinel
Use put_file_non_atomic in lockdir() to save some sftp round trips
204
            # We use put_file_non_atomic because we just created a new unique
205
            # directory so we don't have to worry about files existing there.
206
            # We'll rename the whole directory into place to get atomic
207
            # properties
1993.1.2 by John Arbash Meinel
Use Stanza.to_string() rather than a RioWriter
208
            self.transport.put_bytes_non_atomic(tmpname + self.__INFO_NAME,
209
                                                info_bytes)
1955.1.1 by John Arbash Meinel
LockDir can create the root directory if it fails to create a pending directory due to NoSuchFile.
210
1553.5.58 by Martin Pool
Change LockDirs to format "lock-name/held/info"
211
            self.transport.rename(tmpname, self._held_dir)
1553.5.12 by Martin Pool
New LockDir locking mechanism
212
            self._lock_held = True
1553.5.33 by Martin Pool
LockDir review comment fixes
213
            self.confirm()
1662.1.12 by Martin Pool
Translate unknown sftp errors to PathError, no NoSuchFile
214
        except (PathError, DirectoryNotEmpty, FileExists, ResourceBusy), e:
215
            mutter("contention on %r: %s", self, e)
216
            raise LockContention(self)
1553.5.12 by Martin Pool
New LockDir locking mechanism
217
218
    def unlock(self):
1553.5.30 by Martin Pool
docstring for LockDir.unlock
219
        """Release a held lock
220
        """
1553.5.54 by Martin Pool
Add LockDir.read_lock fake method
221
        if self._fake_read_lock:
222
            self._fake_read_lock = False
223
            return
1553.5.12 by Martin Pool
New LockDir locking mechanism
224
        if not self._lock_held:
225
            raise LockNotHeld(self)
226
        # rename before deleting, because we can't atomically remove the whole
227
        # tree
1553.5.58 by Martin Pool
Change LockDirs to format "lock-name/held/info"
228
        tmpname = '%s/releasing.%s.tmp' % (self.path, rand_chars(20))
1687.1.3 by Robert Collins
Make LockDir.unlock check the lock is still intact.
229
        # gotta own it to unlock
230
        self.confirm()
1553.5.58 by Martin Pool
Change LockDirs to format "lock-name/held/info"
231
        self.transport.rename(self._held_dir, tmpname)
1553.5.12 by Martin Pool
New LockDir locking mechanism
232
        self._lock_held = False
1553.5.33 by Martin Pool
LockDir review comment fixes
233
        self.transport.delete(tmpname + self.__INFO_NAME)
1553.5.12 by Martin Pool
New LockDir locking mechanism
234
        self.transport.rmdir(tmpname)
235
1687.1.5 by Robert Collins
Add break_lock utility function to LockDir.
236
    def break_lock(self):
237
        """Break a lock not held by this instance of LockDir.
238
239
        This is a UI centric function: it uses the bzrlib.ui.ui_factory to
240
        prompt for input if a lock is detected and there is any doubt about
241
        it possibly being still active.
242
        """
1687.1.6 by Robert Collins
Extend LockableFiles to support break_lock() calls.
243
        self._check_not_locked()
1687.1.5 by Robert Collins
Add break_lock utility function to LockDir.
244
        holder_info = self.peek()
245
        if holder_info is not None:
246
            if bzrlib.ui.ui_factory.get_boolean(
1687.1.15 by Robert Collins
Review comments.
247
                "Break lock %s held by %s@%s [process #%s]" % (
1687.1.5 by Robert Collins
Add break_lock utility function to LockDir.
248
                    self.transport,
249
                    holder_info["user"],
1687.1.15 by Robert Collins
Review comments.
250
                    holder_info["hostname"],
251
                    holder_info["pid"])):
1687.1.5 by Robert Collins
Add break_lock utility function to LockDir.
252
                self.force_break(holder_info)
253
        
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
254
    def force_break(self, dead_holder_info):
1553.5.25 by Martin Pool
New LockDir.force_break and simple test case
255
        """Release a lock held by another process.
256
257
        WARNING: This should only be used when the other process is dead; if
258
        it still thinks it has the lock there will be two concurrent writers.
259
        In general the user's approval should be sought for lock breaks.
260
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
261
        dead_holder_info must be the result of a previous LockDir.peek() call;
262
        this is used to check that it's still held by the same process that
263
        the user decided was dead.  If this is not the current holder,
264
        LockBreakMismatch is raised.
265
1553.5.25 by Martin Pool
New LockDir.force_break and simple test case
266
        After the lock is broken it will not be held by any process.
267
        It is possible that another process may sneak in and take the 
268
        lock before the breaking process acquires it.
269
        """
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
270
        if not isinstance(dead_holder_info, dict):
271
            raise ValueError("dead_holder_info: %r" % dead_holder_info)
1687.1.6 by Robert Collins
Extend LockableFiles to support break_lock() calls.
272
        self._check_not_locked()
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
273
        current_info = self.peek()
274
        if current_info is None:
1553.5.26 by Martin Pool
Breaking an already-released lock should just succeed
275
            # must have been recently released
276
            return
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
277
        if current_info != dead_holder_info:
278
            raise LockBreakMismatch(self, current_info, dead_holder_info)
1553.5.58 by Martin Pool
Change LockDirs to format "lock-name/held/info"
279
        tmpname = '%s/broken.%s.tmp' % (self.path, rand_chars(20))
280
        self.transport.rename(self._held_dir, tmpname)
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
281
        # check that we actually broke the right lock, not someone else;
282
        # there's a small race window between checking it and doing the 
283
        # rename.
1553.5.33 by Martin Pool
LockDir review comment fixes
284
        broken_info_path = tmpname + self.__INFO_NAME
285
        broken_info = self._read_info_file(broken_info_path)
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
286
        if broken_info != dead_holder_info:
287
            raise LockBreakMismatch(self, broken_info, dead_holder_info)
288
        self.transport.delete(broken_info_path)
1553.5.25 by Martin Pool
New LockDir.force_break and simple test case
289
        self.transport.rmdir(tmpname)
290
1687.1.6 by Robert Collins
Extend LockableFiles to support break_lock() calls.
291
    def _check_not_locked(self):
292
        """If the lock is held by this instance, raise an error."""
293
        if self._lock_held:
294
            raise AssertionError("can't break own lock: %r" % self)
295
1553.5.20 by Martin Pool
Start adding LockDir.confirm() method
296
    def confirm(self):
297
        """Make sure that the lock is still held by this locker.
298
299
        This should only fail if the lock was broken by user intervention,
300
        or if the lock has been affected by a bug.
301
302
        If the lock is not thought to be held, raises LockNotHeld.  If
303
        the lock is thought to be held but has been broken, raises 
304
        LockBroken.
305
        """
306
        if not self._lock_held:
307
            raise LockNotHeld(self)
1553.5.23 by Martin Pool
Start LockDir.confirm method and LockBroken exception
308
        info = self.peek()
309
        if info is None:
310
            # no lock there anymore!
311
            raise LockBroken(self)
312
        if info.get('nonce') != self.nonce:
313
            # there is a lock, but not ours
314
            raise LockBroken(self)
1553.5.33 by Martin Pool
LockDir review comment fixes
315
        
316
    def _read_info_file(self, path):
1553.5.58 by Martin Pool
Change LockDirs to format "lock-name/held/info"
317
        """Read one given info file.
318
319
        peek() reads the info file of the lock holder, if any.
320
        """
1553.5.33 by Martin Pool
LockDir review comment fixes
321
        return self._parse_info(self.transport.get(path))
1553.5.20 by Martin Pool
Start adding LockDir.confirm() method
322
1553.5.12 by Martin Pool
New LockDir locking mechanism
323
    def peek(self):
324
        """Check if the lock is held by anyone.
325
        
326
        If it is held, this returns the lock info structure as a rio Stanza,
327
        which contains some information about the current lock holder.
328
        Otherwise returns None.
329
        """
330
        try:
1553.5.58 by Martin Pool
Change LockDirs to format "lock-name/held/info"
331
            info = self._read_info_file(self._held_info_path)
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
332
            assert isinstance(info, dict), \
1553.5.12 by Martin Pool
New LockDir locking mechanism
333
                    "bad parse result %r" % info
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
334
            return info
1553.5.12 by Martin Pool
New LockDir locking mechanism
335
        except NoSuchFile, e:
336
            return None
337
1993.1.2 by John Arbash Meinel
Use Stanza.to_string() rather than a RioWriter
338
    def _prepare_info(self):
1553.5.12 by Martin Pool
New LockDir locking mechanism
339
        """Write information about a pending lock to a temporary file.
340
        """
341
        import socket
342
        # XXX: is creating this here inefficient?
343
        config = bzrlib.config.GlobalConfig()
344
        s = Stanza(hostname=socket.gethostname(),
345
                   pid=str(os.getpid()),
346
                   start_time=str(int(time.time())),
347
                   nonce=self.nonce,
348
                   user=config.user_email(),
349
                   )
1993.1.2 by John Arbash Meinel
Use Stanza.to_string() rather than a RioWriter
350
        return s.to_string()
1553.5.12 by Martin Pool
New LockDir locking mechanism
351
352
    def _parse_info(self, info_file):
1553.5.27 by Martin Pool
Confirm that only the intended holder of a lock was broken.
353
        return read_stanza(info_file.readlines()).as_dict()
1553.5.12 by Martin Pool
New LockDir locking mechanism
354
1553.5.21 by Martin Pool
Put default LockDir timeouts in variables; increase timeout to 3min
355
    def wait_lock(self, timeout=_DEFAULT_TIMEOUT_SECONDS,
356
                  poll=_DEFAULT_POLL_SECONDS):
1553.5.12 by Martin Pool
New LockDir locking mechanism
357
        """Wait a certain period for a lock.
358
359
        If the lock can be acquired within the bounded time, it
360
        is taken and this returns.  Otherwise, LockContention
361
        is raised.  Either way, this function should return within
362
        approximately `timeout` seconds.  (It may be a bit more if
363
        a transport operation takes a long time to complete.)
364
        """
365
        # XXX: the transport interface doesn't let us guard 
366
        # against operations there taking a long time.
367
        deadline = time.time() + timeout
368
        while True:
369
            try:
370
                self.attempt_lock()
371
                return
372
            except LockContention:
373
                pass
374
            if time.time() + poll < deadline:
375
                time.sleep(poll)
376
            else:
377
                raise LockContention(self)
378
1553.5.44 by Martin Pool
LockableFiles can now call LockDir directly
379
    def lock_write(self):
380
        """Wait for and acquire the lock."""
381
        self.attempt_lock()
382
383
    def lock_read(self):
1759.2.1 by Jelmer Vernooij
Fix some types (found using aspell).
384
        """Compatibility-mode shared lock.
1553.5.44 by Martin Pool
LockableFiles can now call LockDir directly
385
386
        LockDir doesn't support shared read-only locks, so this 
1553.5.54 by Martin Pool
Add LockDir.read_lock fake method
387
        just pretends that the lock is taken but really does nothing.
1553.5.44 by Martin Pool
LockableFiles can now call LockDir directly
388
        """
389
        # At the moment Branches are commonly locked for read, but 
390
        # we can't rely on that remotely.  Once this is cleaned up,
391
        # reenable this warning to prevent it coming back in 
392
        # -- mbp 20060303
393
        ## warn("LockDir.lock_read falls back to write lock")
1553.5.54 by Martin Pool
Add LockDir.read_lock fake method
394
        if self._lock_held or self._fake_read_lock:
395
            raise LockContention(self)
396
        self._fake_read_lock = True
1553.5.44 by Martin Pool
LockableFiles can now call LockDir directly
397
1553.5.12 by Martin Pool
New LockDir locking mechanism
398
    def wait(self, timeout=20, poll=0.5):
1553.5.33 by Martin Pool
LockDir review comment fixes
399
        """Wait a certain period for a lock to be released."""
1553.5.12 by Martin Pool
New LockDir locking mechanism
400
        # XXX: the transport interface doesn't let us guard 
401
        # against operations there taking a long time.
402
        deadline = time.time() + timeout
403
        while True:
404
            if self.peek():
405
                return
406
            if time.time() + poll < deadline:
407
                time.sleep(poll)
408
            else:
409
                raise LockContention(self)
1553.5.25 by Martin Pool
New LockDir.force_break and simple test case
410