~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/lockdir.py

  • Committer: Robert Collins
  • Date: 2007-07-04 02:43:26 UTC
  • mto: This revision was merged to the branch mainline in revision 2581.
  • Revision ID: robertc@robertcollins.net-20070704024326-czaqy9flaooda2jj
Fix missed tests.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
# Copyright (C) 2006 Canonical Ltd
 
2
#
 
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.
 
7
#
 
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.
 
12
#
 
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
 
 
17
"""On-disk mutex protecting a resource
 
18
 
 
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.
 
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
 
 
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')
 
90
>>> l.create()
 
91
>>> l.wait_lock()
 
92
>>> # do something here
 
93
>>> l.unlock()
 
94
 
 
95
"""
 
96
 
 
97
import os
 
98
import time
 
99
from cStringIO import StringIO
 
100
 
 
101
from bzrlib import (
 
102
    errors,
 
103
    )
 
104
import bzrlib.config
 
105
from bzrlib.errors import (
 
106
        DirectoryNotEmpty,
 
107
        FileExists,
 
108
        LockBreakMismatch,
 
109
        LockBroken,
 
110
        LockContention,
 
111
        LockNotHeld,
 
112
        NoSuchFile,
 
113
        PathError,
 
114
        ResourceBusy,
 
115
        UnlockableTransport,
 
116
        )
 
117
from bzrlib.trace import mutter, note
 
118
from bzrlib.transport import Transport
 
119
from bzrlib.osutils import rand_chars, format_delta
 
120
from bzrlib.rio import read_stanza, Stanza
 
121
import bzrlib.ui
 
122
 
 
123
 
 
124
# XXX: At the moment there is no consideration of thread safety on LockDir
 
125
# objects.  This should perhaps be updated - e.g. if two threads try to take a
 
126
# lock at the same time they should *both* get it.  But then that's unlikely
 
127
# to be a good idea.
 
128
 
 
129
# TODO: Perhaps store some kind of note like the bzr command line in the lock
 
130
# info?
 
131
 
 
132
# TODO: Some kind of callback run while polling a lock to show progress
 
133
# indicators.
 
134
 
 
135
# TODO: Make sure to pass the right file and directory mode bits to all
 
136
# files/dirs created.
 
137
 
 
138
 
 
139
_DEFAULT_TIMEOUT_SECONDS = 300
 
140
_DEFAULT_POLL_SECONDS = 1.0
 
141
 
 
142
 
 
143
class LockDir(object):
 
144
    """Write-lock guarding access to data."""
 
145
 
 
146
    __INFO_NAME = '/info'
 
147
 
 
148
    def __init__(self, transport, path, file_modebits=0644, dir_modebits=0755):
 
149
        """Create a new LockDir object.
 
150
 
 
151
        The LockDir is initially unlocked - this just creates the object.
 
152
 
 
153
        :param transport: Transport which will contain the lock
 
154
 
 
155
        :param path: Path to the lock within the base directory of the 
 
156
            transport.
 
157
        """
 
158
        assert isinstance(transport, Transport), \
 
159
            ("not a transport: %r" % transport)
 
160
        self.transport = transport
 
161
        self.path = path
 
162
        self._lock_held = False
 
163
        self._locked_via_token = False
 
164
        self._fake_read_lock = False
 
165
        self._held_dir = path + '/held'
 
166
        self._held_info_path = self._held_dir + self.__INFO_NAME
 
167
        self._file_modebits = file_modebits
 
168
        self._dir_modebits = dir_modebits
 
169
 
 
170
        self._report_function = note
 
171
 
 
172
    def __repr__(self):
 
173
        return '%s(%s%s)' % (self.__class__.__name__,
 
174
                             self.transport.base,
 
175
                             self.path)
 
176
 
 
177
    is_held = property(lambda self: self._lock_held)
 
178
 
 
179
    def create(self, mode=None):
 
180
        """Create the on-disk lock.
 
181
 
 
182
        This is typically only called when the object/directory containing the 
 
183
        directory is first created.  The lock is not held when it's created.
 
184
        """
 
185
        if self.transport.is_readonly():
 
186
            raise UnlockableTransport(self.transport)
 
187
        self.transport.mkdir(self.path, mode=mode)
 
188
 
 
189
    def attempt_lock(self):
 
190
        """Take the lock; fail if it's already held.
 
191
        
 
192
        If you wish to block until the lock can be obtained, call wait_lock()
 
193
        instead.
 
194
        """
 
195
        if self._fake_read_lock:
 
196
            raise LockContention(self)
 
197
        if self.transport.is_readonly():
 
198
            raise UnlockableTransport(self.transport)
 
199
        try:
 
200
            tmpname = '%s/pending.%s.tmp' % (self.path, rand_chars(20))
 
201
            try:
 
202
                self.transport.mkdir(tmpname)
 
203
            except NoSuchFile:
 
204
                # This may raise a FileExists exception
 
205
                # which is okay, it will be caught later and determined
 
206
                # to be a LockContention.
 
207
                self.create(mode=self._dir_modebits)
 
208
                
 
209
                # After creating the lock directory, try again
 
210
                self.transport.mkdir(tmpname)
 
211
 
 
212
            self.nonce = rand_chars(20)
 
213
            info_bytes = self._prepare_info()
 
214
            # We use put_file_non_atomic because we just created a new unique
 
215
            # directory so we don't have to worry about files existing there.
 
216
            # We'll rename the whole directory into place to get atomic
 
217
            # properties
 
218
            self.transport.put_bytes_non_atomic(tmpname + self.__INFO_NAME,
 
219
                                                info_bytes)
 
220
 
 
221
            self.transport.rename(tmpname, self._held_dir)
 
222
            self._lock_held = True
 
223
            self.confirm()
 
224
        except errors.PermissionDenied:
 
225
            raise
 
226
        except (PathError, DirectoryNotEmpty, FileExists, ResourceBusy), e:
 
227
            mutter("contention on %r: %s", self, e)
 
228
            raise LockContention(self)
 
229
 
 
230
    def unlock(self):
 
231
        """Release a held lock
 
232
        """
 
233
        if self._fake_read_lock:
 
234
            self._fake_read_lock = False
 
235
            return
 
236
        if not self._lock_held:
 
237
            raise LockNotHeld(self)
 
238
        if self._locked_via_token:
 
239
            self._locked_via_token = False
 
240
            self._lock_held = False
 
241
        else:
 
242
            # rename before deleting, because we can't atomically remove the
 
243
            # whole tree
 
244
            tmpname = '%s/releasing.%s.tmp' % (self.path, rand_chars(20))
 
245
            # gotta own it to unlock
 
246
            self.confirm()
 
247
            self.transport.rename(self._held_dir, tmpname)
 
248
            self._lock_held = False
 
249
            self.transport.delete(tmpname + self.__INFO_NAME)
 
250
            self.transport.rmdir(tmpname)
 
251
 
 
252
    def break_lock(self):
 
253
        """Break a lock not held by this instance of LockDir.
 
254
 
 
255
        This is a UI centric function: it uses the bzrlib.ui.ui_factory to
 
256
        prompt for input if a lock is detected and there is any doubt about
 
257
        it possibly being still active.
 
258
        """
 
259
        self._check_not_locked()
 
260
        holder_info = self.peek()
 
261
        if holder_info is not None:
 
262
            lock_info = '\n'.join(self._format_lock_info(holder_info))
 
263
            if bzrlib.ui.ui_factory.get_boolean("Break %s" % lock_info):
 
264
                self.force_break(holder_info)
 
265
        
 
266
    def force_break(self, dead_holder_info):
 
267
        """Release a lock held by another process.
 
268
 
 
269
        WARNING: This should only be used when the other process is dead; if
 
270
        it still thinks it has the lock there will be two concurrent writers.
 
271
        In general the user's approval should be sought for lock breaks.
 
272
 
 
273
        dead_holder_info must be the result of a previous LockDir.peek() call;
 
274
        this is used to check that it's still held by the same process that
 
275
        the user decided was dead.  If this is not the current holder,
 
276
        LockBreakMismatch is raised.
 
277
 
 
278
        After the lock is broken it will not be held by any process.
 
279
        It is possible that another process may sneak in and take the 
 
280
        lock before the breaking process acquires it.
 
281
        """
 
282
        if not isinstance(dead_holder_info, dict):
 
283
            raise ValueError("dead_holder_info: %r" % dead_holder_info)
 
284
        self._check_not_locked()
 
285
        current_info = self.peek()
 
286
        if current_info is None:
 
287
            # must have been recently released
 
288
            return
 
289
        if current_info != dead_holder_info:
 
290
            raise LockBreakMismatch(self, current_info, dead_holder_info)
 
291
        tmpname = '%s/broken.%s.tmp' % (self.path, rand_chars(20))
 
292
        self.transport.rename(self._held_dir, tmpname)
 
293
        # check that we actually broke the right lock, not someone else;
 
294
        # there's a small race window between checking it and doing the 
 
295
        # rename.
 
296
        broken_info_path = tmpname + self.__INFO_NAME
 
297
        broken_info = self._read_info_file(broken_info_path)
 
298
        if broken_info != dead_holder_info:
 
299
            raise LockBreakMismatch(self, broken_info, dead_holder_info)
 
300
        self.transport.delete(broken_info_path)
 
301
        self.transport.rmdir(tmpname)
 
302
 
 
303
    def _check_not_locked(self):
 
304
        """If the lock is held by this instance, raise an error."""
 
305
        if self._lock_held:
 
306
            raise AssertionError("can't break own lock: %r" % self)
 
307
 
 
308
    def confirm(self):
 
309
        """Make sure that the lock is still held by this locker.
 
310
 
 
311
        This should only fail if the lock was broken by user intervention,
 
312
        or if the lock has been affected by a bug.
 
313
 
 
314
        If the lock is not thought to be held, raises LockNotHeld.  If
 
315
        the lock is thought to be held but has been broken, raises 
 
316
        LockBroken.
 
317
        """
 
318
        if not self._lock_held:
 
319
            raise LockNotHeld(self)
 
320
        info = self.peek()
 
321
        if info is None:
 
322
            # no lock there anymore!
 
323
            raise LockBroken(self)
 
324
        if info.get('nonce') != self.nonce:
 
325
            # there is a lock, but not ours
 
326
            raise LockBroken(self)
 
327
        
 
328
    def _read_info_file(self, path):
 
329
        """Read one given info file.
 
330
 
 
331
        peek() reads the info file of the lock holder, if any.
 
332
        """
 
333
        return self._parse_info(self.transport.get(path))
 
334
 
 
335
    def peek(self):
 
336
        """Check if the lock is held by anyone.
 
337
        
 
338
        If it is held, this returns the lock info structure as a rio Stanza,
 
339
        which contains some information about the current lock holder.
 
340
        Otherwise returns None.
 
341
        """
 
342
        try:
 
343
            info = self._read_info_file(self._held_info_path)
 
344
            assert isinstance(info, dict), \
 
345
                    "bad parse result %r" % info
 
346
            return info
 
347
        except NoSuchFile, e:
 
348
            return None
 
349
 
 
350
    def _prepare_info(self):
 
351
        """Write information about a pending lock to a temporary file.
 
352
        """
 
353
        import socket
 
354
        # XXX: is creating this here inefficient?
 
355
        config = bzrlib.config.GlobalConfig()
 
356
        try:
 
357
            user = config.user_email()
 
358
        except errors.NoEmailInUsername:
 
359
            user = config.username()
 
360
        s = Stanza(hostname=socket.gethostname(),
 
361
                   pid=str(os.getpid()),
 
362
                   start_time=str(int(time.time())),
 
363
                   nonce=self.nonce,
 
364
                   user=user,
 
365
                   )
 
366
        return s.to_string()
 
367
 
 
368
    def _parse_info(self, info_file):
 
369
        return read_stanza(info_file.readlines()).as_dict()
 
370
 
 
371
    def wait_lock(self, timeout=None, poll=None):
 
372
        """Wait a certain period for a lock.
 
373
 
 
374
        If the lock can be acquired within the bounded time, it
 
375
        is taken and this returns.  Otherwise, LockContention
 
376
        is raised.  Either way, this function should return within
 
377
        approximately `timeout` seconds.  (It may be a bit more if
 
378
        a transport operation takes a long time to complete.)
 
379
        """
 
380
        if timeout is None:
 
381
            timeout = _DEFAULT_TIMEOUT_SECONDS
 
382
        if poll is None:
 
383
            poll = _DEFAULT_POLL_SECONDS
 
384
 
 
385
        # XXX: the transport interface doesn't let us guard 
 
386
        # against operations there taking a long time.
 
387
        deadline = time.time() + timeout
 
388
        deadline_str = None
 
389
        last_info = None
 
390
        while True:
 
391
            try:
 
392
                self.attempt_lock()
 
393
                return
 
394
            except LockContention:
 
395
                pass
 
396
            new_info = self.peek()
 
397
            mutter('last_info: %s, new info: %s', last_info, new_info)
 
398
            if new_info is not None and new_info != last_info:
 
399
                if last_info is None:
 
400
                    start = 'Unable to obtain'
 
401
                else:
 
402
                    start = 'Lock owner changed for'
 
403
                last_info = new_info
 
404
                formatted_info = self._format_lock_info(new_info)
 
405
                if deadline_str is None:
 
406
                    deadline_str = time.strftime('%H:%M:%S',
 
407
                                                 time.localtime(deadline))
 
408
                self._report_function('%s %s\n'
 
409
                                      '%s\n' # held by
 
410
                                      '%s\n' # locked ... ago
 
411
                                      'Will continue to try until %s\n',
 
412
                                      start,
 
413
                                      formatted_info[0],
 
414
                                      formatted_info[1],
 
415
                                      formatted_info[2],
 
416
                                      deadline_str)
 
417
 
 
418
            if time.time() + poll < deadline:
 
419
                time.sleep(poll)
 
420
            else:
 
421
                raise LockContention(self)
 
422
    
 
423
    def leave_in_place(self):
 
424
        self._locked_via_token = True
 
425
 
 
426
    def dont_leave_in_place(self):
 
427
        self._locked_via_token = False
 
428
 
 
429
    def lock_write(self, token=None):
 
430
        """Wait for and acquire the lock.
 
431
        
 
432
        :param token: if this is already locked, then lock_write will fail
 
433
            unless the token matches the existing lock.
 
434
        :returns: a token if this instance supports tokens, otherwise None.
 
435
        :raises TokenLockingNotSupported: when a token is given but this
 
436
            instance doesn't support using token locks.
 
437
        :raises MismatchedToken: if the specified token doesn't match the token
 
438
            of the existing lock.
 
439
 
 
440
        A token should be passed in if you know that you have locked the object
 
441
        some other way, and need to synchronise this object's state with that
 
442
        fact.
 
443
         
 
444
        XXX: docstring duplicated from LockableFiles.lock_write.
 
445
        """
 
446
        if token is not None:
 
447
            self.validate_token(token)
 
448
            self.nonce = token
 
449
            self._lock_held = True
 
450
            self._locked_via_token = True
 
451
            return token
 
452
        else:
 
453
            self.wait_lock()
 
454
            return self.peek().get('nonce')
 
455
 
 
456
    def lock_read(self):
 
457
        """Compatibility-mode shared lock.
 
458
 
 
459
        LockDir doesn't support shared read-only locks, so this 
 
460
        just pretends that the lock is taken but really does nothing.
 
461
        """
 
462
        # At the moment Branches are commonly locked for read, but 
 
463
        # we can't rely on that remotely.  Once this is cleaned up,
 
464
        # reenable this warning to prevent it coming back in 
 
465
        # -- mbp 20060303
 
466
        ## warn("LockDir.lock_read falls back to write lock")
 
467
        if self._lock_held or self._fake_read_lock:
 
468
            raise LockContention(self)
 
469
        self._fake_read_lock = True
 
470
 
 
471
    def wait(self, timeout=20, poll=0.5):
 
472
        """Wait a certain period for a lock to be released."""
 
473
        # XXX: the transport interface doesn't let us guard 
 
474
        # against operations there taking a long time.
 
475
        deadline = time.time() + timeout
 
476
        while True:
 
477
            if self.peek():
 
478
                return
 
479
            if time.time() + poll < deadline:
 
480
                time.sleep(poll)
 
481
            else:
 
482
                raise LockContention(self)
 
483
 
 
484
    def _format_lock_info(self, info):
 
485
        """Turn the contents of peek() into something for the user"""
 
486
        lock_url = self.transport.abspath(self.path)
 
487
        delta = time.time() - int(info['start_time'])
 
488
        return [
 
489
            'lock %s' % (lock_url,),
 
490
            'held by %(user)s on host %(hostname)s [process #%(pid)s]' % info,
 
491
            'locked %s' % (format_delta(delta),),
 
492
            ]
 
493
 
 
494
    def validate_token(self, token):
 
495
        if token is not None:
 
496
            info = self.peek()
 
497
            if info is None:
 
498
                # Lock isn't held
 
499
                lock_token = None
 
500
            else:
 
501
                lock_token = info.get('nonce')
 
502
            if token != lock_token:
 
503
                raise errors.TokenMismatch(token, lock_token)
 
504