← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/lockdir.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2011-05-04 12:10:51 UTC
  • mfrom: (5819.1.4 777007-developer-doc)
  • Revision ID: pqm@pqm.ubuntu.com-20110504121051-aovlsmqiivjmc4fc
(jelmer) Small fixes to developer documentation. (Jonathan Riddell)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/lockdir.py
1
 
# Copyright (C) 2006 Canonical Ltd
 
1
# Copyright (C) 2006-2011 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
12
12
#
13
13
# You should have received a copy of the GNU General Public License
14
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
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
17
17
"""On-disk mutex protecting a resource
18
18
 
21
21
internal locks (such as flock etc) because they can be seen across all
22
22
transports, including http.
23
23
 
24
 
Objects can be read if there is only physical read access; therefore 
 
24
Objects can be read if there is only physical read access; therefore
25
25
readers can never be required to create a lock, though they will
26
26
check whether a writer is using the lock.  Writers can't detect
27
27
whether anyone else is reading from the resource as they write.
56
56
 
57
57
The desired characteristics are:
58
58
 
59
 
* Locks are not reentrant.  (That is, a client that tries to take a 
 
59
* Locks are not reentrant.  (That is, a client that tries to take a
60
60
  lock it already holds may deadlock or fail.)
61
61
* Stale locks can be guessed at by a heuristic
62
62
* Lost locks can be broken by any client
78
78
and deadlocks will likely occur if the locks are aliased.
79
79
 
80
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 
 
81
by a lock holder to check that their lock has not been broken, and to
82
82
update the timestamp within it.
83
83
 
84
84
Example usage:
88
88
>>> t = MemoryTransport()
89
89
>>> l = LockDir(t, 'sample-lock')
90
90
>>> l.create()
91
 
>>> l.wait_lock()
 
91
>>> token = l.wait_lock()
92
92
>>> # do something here
93
93
>>> l.unlock()
94
94
 
95
95
"""
96
96
 
 
97
 
 
98
# TODO: We sometimes have the problem that our attempt to rename '1234' to
 
99
# 'held' fails because the transport server moves into an existing directory,
 
100
# rather than failing the rename.  If we made the info file name the same as
 
101
# the locked directory name we would avoid this problem because moving into
 
102
# the held directory would implicitly clash.  However this would not mesh with
 
103
# the existing locking code and needs a new format of the containing object.
 
104
# -- robertc, mbp 20070628
 
105
 
97
106
import os
98
107
import time
99
 
from cStringIO import StringIO
100
108
 
101
109
from bzrlib import (
 
110
    debug,
102
111
    errors,
 
112
    lock,
 
113
    osutils,
103
114
    )
104
115
import bzrlib.config
 
116
from bzrlib.decorators import only_raises
105
117
from bzrlib.errors import (
106
118
        DirectoryNotEmpty,
107
119
        FileExists,
108
120
        LockBreakMismatch,
109
121
        LockBroken,
110
122
        LockContention,
 
123
        LockCorrupt,
 
124
        LockFailed,
111
125
        LockNotHeld,
112
126
        NoSuchFile,
113
127
        PathError,
114
128
        ResourceBusy,
115
 
        UnlockableTransport,
 
129
        TransportError,
116
130
        )
117
131
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
 
132
from bzrlib.osutils import format_delta, rand_chars, get_host_name
121
133
import bzrlib.ui
122
134
 
 
135
from bzrlib.lazy_import import lazy_import
 
136
lazy_import(globals(), """
 
137
from bzrlib import rio
 
138
""")
123
139
 
124
140
# XXX: At the moment there is no consideration of thread safety on LockDir
125
141
# objects.  This should perhaps be updated - e.g. if two threads try to take a
136
152
# files/dirs created.
137
153
 
138
154
 
139
 
_DEFAULT_TIMEOUT_SECONDS = 300
 
155
_DEFAULT_TIMEOUT_SECONDS = 30
140
156
_DEFAULT_POLL_SECONDS = 1.0
141
157
 
142
158
 
143
 
class LockDir(object):
144
 
    """Write-lock guarding access to data."""
 
159
class LockDir(lock.Lock):
 
160
    """Write-lock guarding access to data.
 
161
    """
145
162
 
146
163
    __INFO_NAME = '/info'
147
164
 
152
169
 
153
170
        :param transport: Transport which will contain the lock
154
171
 
155
 
        :param path: Path to the lock within the base directory of the 
 
172
        :param path: Path to the lock within the base directory of the
156
173
            transport.
157
174
        """
158
 
        assert isinstance(transport, Transport), \
159
 
            ("not a transport: %r" % transport)
160
175
        self.transport = transport
161
176
        self.path = path
162
177
        self._lock_held = False
 
178
        self._locked_via_token = False
163
179
        self._fake_read_lock = False
164
180
        self._held_dir = path + '/held'
165
181
        self._held_info_path = self._held_dir + self.__INFO_NAME
166
182
        self._file_modebits = file_modebits
167
183
        self._dir_modebits = dir_modebits
168
 
        self.nonce = rand_chars(20)
169
184
 
170
185
        self._report_function = note
171
186
 
179
194
    def create(self, mode=None):
180
195
        """Create the on-disk lock.
181
196
 
182
 
        This is typically only called when the object/directory containing the 
 
197
        This is typically only called when the object/directory containing the
183
198
        directory is first created.  The lock is not held when it's created.
184
199
        """
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.
 
200
        self._trace("create lock directory")
 
201
        try:
 
202
            self.transport.mkdir(self.path, mode=mode)
 
203
        except (TransportError, PathError), e:
 
204
            raise LockFailed(self, e)
 
205
 
 
206
 
 
207
    def _attempt_lock(self):
 
208
        """Make the pending directory and attempt to rename into place.
 
209
 
 
210
        If the rename succeeds, we read back the info file to check that we
 
211
        really got the lock.
 
212
 
 
213
        If we fail to acquire the lock, this method is responsible for
 
214
        cleaning up the pending directory if possible.  (But it doesn't do
 
215
        that yet.)
 
216
 
 
217
        :returns: The nonce of the lock, if it was successfully acquired.
 
218
 
 
219
        :raises LockContention: If the lock is held by someone else.  The exception
 
220
            contains the info of the current holder of the lock.
194
221
        """
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
 
            info_bytes = self._prepare_info()
213
 
            # We use put_file_non_atomic because we just created a new unique
214
 
            # directory so we don't have to worry about files existing there.
215
 
            # We'll rename the whole directory into place to get atomic
216
 
            # properties
217
 
            self.transport.put_bytes_non_atomic(tmpname + self.__INFO_NAME,
218
 
                                                info_bytes)
219
 
 
 
222
        self._trace("lock_write...")
 
223
        start_time = time.time()
 
224
        try:
 
225
            tmpname = self._create_pending_dir()
 
226
        except (errors.TransportError, PathError), e:
 
227
            self._trace("... failed to create pending dir, %s", e)
 
228
            raise LockFailed(self, e)
 
229
        try:
220
230
            self.transport.rename(tmpname, self._held_dir)
221
 
            self._lock_held = True
222
 
            self.confirm()
223
 
        except (PathError, DirectoryNotEmpty, FileExists, ResourceBusy), e:
224
 
            mutter("contention on %r: %s", self, e)
225
 
            raise LockContention(self)
226
 
 
 
231
        except (errors.TransportError, PathError, DirectoryNotEmpty,
 
232
                FileExists, ResourceBusy), e:
 
233
            self._trace("... contention, %s", e)
 
234
            self._remove_pending_dir(tmpname)
 
235
            raise LockContention(self)
 
236
        except Exception, e:
 
237
            self._trace("... lock failed, %s", e)
 
238
            self._remove_pending_dir(tmpname)
 
239
            raise
 
240
        # We must check we really got the lock, because Launchpad's sftp
 
241
        # server at one time had a bug were the rename would successfully
 
242
        # move the new directory into the existing directory, which was
 
243
        # incorrect.  It's possible some other servers or filesystems will
 
244
        # have a similar bug allowing someone to think they got the lock
 
245
        # when it's already held.
 
246
        #
 
247
        # See <https://bugs.launchpad.net/bzr/+bug/498378> for one case.
 
248
        #
 
249
        # Strictly the check is unnecessary and a waste of time for most
 
250
        # people, but probably worth trapping if something is wrong.
 
251
        info = self.peek()
 
252
        self._trace("after locking, info=%r", info)
 
253
        if info is None:
 
254
            raise LockFailed(self, "lock was renamed into place, but "
 
255
                "now is missing!")
 
256
        if info.get('nonce') != self.nonce:
 
257
            self._trace("rename succeeded, "
 
258
                "but lock is still held by someone else")
 
259
            raise LockContention(self)
 
260
        self._lock_held = True
 
261
        self._trace("... lock succeeded after %dms",
 
262
                (time.time() - start_time) * 1000)
 
263
        return self.nonce
 
264
 
 
265
    def _remove_pending_dir(self, tmpname):
 
266
        """Remove the pending directory
 
267
 
 
268
        This is called if we failed to rename into place, so that the pending
 
269
        dirs don't clutter up the lockdir.
 
270
        """
 
271
        self._trace("remove %s", tmpname)
 
272
        try:
 
273
            self.transport.delete(tmpname + self.__INFO_NAME)
 
274
            self.transport.rmdir(tmpname)
 
275
        except PathError, e:
 
276
            note("error removing pending lock: %s", e)
 
277
 
 
278
    def _create_pending_dir(self):
 
279
        tmpname = '%s/%s.tmp' % (self.path, rand_chars(10))
 
280
        try:
 
281
            self.transport.mkdir(tmpname)
 
282
        except NoSuchFile:
 
283
            # This may raise a FileExists exception
 
284
            # which is okay, it will be caught later and determined
 
285
            # to be a LockContention.
 
286
            self._trace("lock directory does not exist, creating it")
 
287
            self.create(mode=self._dir_modebits)
 
288
            # After creating the lock directory, try again
 
289
            self.transport.mkdir(tmpname)
 
290
        self.nonce = rand_chars(20)
 
291
        info_bytes = self._prepare_info()
 
292
        # We use put_file_non_atomic because we just created a new unique
 
293
        # directory so we don't have to worry about files existing there.
 
294
        # We'll rename the whole directory into place to get atomic
 
295
        # properties
 
296
        self.transport.put_bytes_non_atomic(tmpname + self.__INFO_NAME,
 
297
                                            info_bytes)
 
298
        return tmpname
 
299
 
 
300
    @only_raises(LockNotHeld, LockBroken)
227
301
    def unlock(self):
228
302
        """Release a held lock
229
303
        """
231
305
            self._fake_read_lock = False
232
306
            return
233
307
        if not self._lock_held:
234
 
            raise LockNotHeld(self)
235
 
        # rename before deleting, because we can't atomically remove the whole
236
 
        # tree
237
 
        tmpname = '%s/releasing.%s.tmp' % (self.path, rand_chars(20))
238
 
        # gotta own it to unlock
239
 
        self.confirm()
240
 
        self.transport.rename(self._held_dir, tmpname)
241
 
        self._lock_held = False
242
 
        self.transport.delete(tmpname + self.__INFO_NAME)
243
 
        self.transport.rmdir(tmpname)
 
308
            return lock.cant_unlock_not_held(self)
 
309
        if self._locked_via_token:
 
310
            self._locked_via_token = False
 
311
            self._lock_held = False
 
312
        else:
 
313
            old_nonce = self.nonce
 
314
            # rename before deleting, because we can't atomically remove the
 
315
            # whole tree
 
316
            start_time = time.time()
 
317
            self._trace("unlocking")
 
318
            tmpname = '%s/releasing.%s.tmp' % (self.path, rand_chars(20))
 
319
            # gotta own it to unlock
 
320
            self.confirm()
 
321
            self.transport.rename(self._held_dir, tmpname)
 
322
            self._lock_held = False
 
323
            self.transport.delete(tmpname + self.__INFO_NAME)
 
324
            try:
 
325
                self.transport.rmdir(tmpname)
 
326
            except DirectoryNotEmpty, e:
 
327
                # There might have been junk left over by a rename that moved
 
328
                # another locker within the 'held' directory.  do a slower
 
329
                # deletion where we list the directory and remove everything
 
330
                # within it.
 
331
                #
 
332
                # Maybe this should be broader to allow for ftp servers with
 
333
                # non-specific error messages?
 
334
                self._trace("doing recursive deletion of non-empty directory "
 
335
                        "%s", tmpname)
 
336
                self.transport.delete_tree(tmpname)
 
337
            self._trace("... unlock succeeded after %dms",
 
338
                    (time.time() - start_time) * 1000)
 
339
            result = lock.LockResult(self.transport.abspath(self.path),
 
340
                                     old_nonce)
 
341
            for hook in self.hooks['lock_released']:
 
342
                hook(result)
244
343
 
245
344
    def break_lock(self):
246
345
        """Break a lock not held by this instance of LockDir.
248
347
        This is a UI centric function: it uses the bzrlib.ui.ui_factory to
249
348
        prompt for input if a lock is detected and there is any doubt about
250
349
        it possibly being still active.
 
350
 
 
351
        :returns: LockResult for the broken lock.
251
352
        """
252
353
        self._check_not_locked()
253
 
        holder_info = self.peek()
 
354
        try:
 
355
            holder_info = self.peek()
 
356
        except LockCorrupt, e:
 
357
            # The lock info is corrupt.
 
358
            if bzrlib.ui.ui_factory.get_boolean("Break (corrupt %r)" % (self,)):
 
359
                self.force_break_corrupt(e.file_data)
 
360
            return
254
361
        if holder_info is not None:
255
362
            lock_info = '\n'.join(self._format_lock_info(holder_info))
256
 
            if bzrlib.ui.ui_factory.get_boolean("Break %s" % lock_info):
257
 
                self.force_break(holder_info)
258
 
        
 
363
            if bzrlib.ui.ui_factory.confirm_action(
 
364
                "Break %(lock_info)s", 'bzrlib.lockdir.break', 
 
365
                dict(lock_info=lock_info)):
 
366
                result = self.force_break(holder_info)
 
367
                bzrlib.ui.ui_factory.show_message(
 
368
                    "Broke lock %s" % result.lock_url)
 
369
 
259
370
    def force_break(self, dead_holder_info):
260
371
        """Release a lock held by another process.
261
372
 
269
380
        LockBreakMismatch is raised.
270
381
 
271
382
        After the lock is broken it will not be held by any process.
272
 
        It is possible that another process may sneak in and take the 
 
383
        It is possible that another process may sneak in and take the
273
384
        lock before the breaking process acquires it.
 
385
 
 
386
        :returns: LockResult for the broken lock.
274
387
        """
275
388
        if not isinstance(dead_holder_info, dict):
276
389
            raise ValueError("dead_holder_info: %r" % dead_holder_info)
284
397
        tmpname = '%s/broken.%s.tmp' % (self.path, rand_chars(20))
285
398
        self.transport.rename(self._held_dir, tmpname)
286
399
        # check that we actually broke the right lock, not someone else;
287
 
        # there's a small race window between checking it and doing the 
 
400
        # there's a small race window between checking it and doing the
288
401
        # rename.
289
402
        broken_info_path = tmpname + self.__INFO_NAME
290
403
        broken_info = self._read_info_file(broken_info_path)
292
405
            raise LockBreakMismatch(self, broken_info, dead_holder_info)
293
406
        self.transport.delete(broken_info_path)
294
407
        self.transport.rmdir(tmpname)
 
408
        result = lock.LockResult(self.transport.abspath(self.path),
 
409
                                 current_info.get('nonce'))
 
410
        for hook in self.hooks['lock_broken']:
 
411
            hook(result)
 
412
        return result
 
413
 
 
414
    def force_break_corrupt(self, corrupt_info_lines):
 
415
        """Release a lock that has been corrupted.
 
416
        
 
417
        This is very similar to force_break, it except it doesn't assume that
 
418
        self.peek() can work.
 
419
        
 
420
        :param corrupt_info_lines: the lines of the corrupted info file, used
 
421
            to check that the lock hasn't changed between reading the (corrupt)
 
422
            info file and calling force_break_corrupt.
 
423
        """
 
424
        # XXX: this copes with unparseable info files, but what about missing
 
425
        # info files?  Or missing lock dirs?
 
426
        self._check_not_locked()
 
427
        tmpname = '%s/broken.%s.tmp' % (self.path, rand_chars(20))
 
428
        self.transport.rename(self._held_dir, tmpname)
 
429
        # check that we actually broke the right lock, not someone else;
 
430
        # there's a small race window between checking it and doing the
 
431
        # rename.
 
432
        broken_info_path = tmpname + self.__INFO_NAME
 
433
        broken_content = self.transport.get_bytes(broken_info_path)
 
434
        broken_lines = osutils.split_lines(broken_content)
 
435
        if broken_lines != corrupt_info_lines:
 
436
            raise LockBreakMismatch(self, broken_lines, corrupt_info_lines)
 
437
        self.transport.delete(broken_info_path)
 
438
        self.transport.rmdir(tmpname)
 
439
        result = lock.LockResult(self.transport.abspath(self.path))
 
440
        for hook in self.hooks['lock_broken']:
 
441
            hook(result)
295
442
 
296
443
    def _check_not_locked(self):
297
444
        """If the lock is held by this instance, raise an error."""
305
452
        or if the lock has been affected by a bug.
306
453
 
307
454
        If the lock is not thought to be held, raises LockNotHeld.  If
308
 
        the lock is thought to be held but has been broken, raises 
 
455
        the lock is thought to be held but has been broken, raises
309
456
        LockBroken.
310
457
        """
311
458
        if not self._lock_held:
317
464
        if info.get('nonce') != self.nonce:
318
465
            # there is a lock, but not ours
319
466
            raise LockBroken(self)
320
 
        
 
467
 
321
468
    def _read_info_file(self, path):
322
469
        """Read one given info file.
323
470
 
324
471
        peek() reads the info file of the lock holder, if any.
325
472
        """
326
 
        return self._parse_info(self.transport.get(path))
 
473
        return self._parse_info(self.transport.get_bytes(path))
327
474
 
328
475
    def peek(self):
329
476
        """Check if the lock is held by anyone.
330
 
        
331
 
        If it is held, this returns the lock info structure as a rio Stanza,
 
477
 
 
478
        If it is held, this returns the lock info structure as a dict
332
479
        which contains some information about the current lock holder.
333
480
        Otherwise returns None.
334
481
        """
335
482
        try:
336
483
            info = self._read_info_file(self._held_info_path)
337
 
            assert isinstance(info, dict), \
338
 
                    "bad parse result %r" % info
 
484
            self._trace("peek -> held")
339
485
            return info
340
486
        except NoSuchFile, e:
341
 
            return None
 
487
            self._trace("peek -> not held")
342
488
 
343
489
    def _prepare_info(self):
344
490
        """Write information about a pending lock to a temporary file.
345
491
        """
346
 
        import socket
347
492
        # XXX: is creating this here inefficient?
348
493
        config = bzrlib.config.GlobalConfig()
349
494
        try:
350
 
            user = config.user_email()
351
 
        except errors.NoEmailInUsername:
352
495
            user = config.username()
353
 
        s = Stanza(hostname=socket.gethostname(),
 
496
        except errors.NoWhoami:
 
497
            user = osutils.getuser_unicode()
 
498
        s = rio.Stanza(hostname=get_host_name(),
354
499
                   pid=str(os.getpid()),
355
500
                   start_time=str(int(time.time())),
356
501
                   nonce=self.nonce,
358
503
                   )
359
504
        return s.to_string()
360
505
 
361
 
    def _parse_info(self, info_file):
362
 
        return read_stanza(info_file.readlines()).as_dict()
363
 
 
364
 
    def wait_lock(self, timeout=None, poll=None):
 
506
    def _parse_info(self, info_bytes):
 
507
        lines = osutils.split_lines(info_bytes)
 
508
        try:
 
509
            stanza = rio.read_stanza(lines)
 
510
        except ValueError, e:
 
511
            mutter('Corrupt lock info file: %r', lines)
 
512
            raise LockCorrupt("could not parse lock info file: " + str(e),
 
513
                              lines)
 
514
        if stanza is None:
 
515
            # see bug 185013; we fairly often end up with the info file being
 
516
            # empty after an interruption; we could log a message here but
 
517
            # there may not be much we can say
 
518
            return {}
 
519
        else:
 
520
            return stanza.as_dict()
 
521
 
 
522
    def attempt_lock(self):
 
523
        """Take the lock; fail if it's already held.
 
524
 
 
525
        If you wish to block until the lock can be obtained, call wait_lock()
 
526
        instead.
 
527
 
 
528
        :return: The lock token.
 
529
        :raises LockContention: if the lock is held by someone else.
 
530
        """
 
531
        if self._fake_read_lock:
 
532
            raise LockContention(self)
 
533
        result = self._attempt_lock()
 
534
        hook_result = lock.LockResult(self.transport.abspath(self.path),
 
535
                self.nonce)
 
536
        for hook in self.hooks['lock_acquired']:
 
537
            hook(hook_result)
 
538
        return result
 
539
 
 
540
    def lock_url_for_display(self):
 
541
        """Give a nicely-printable representation of the URL of this lock."""
 
542
        # As local lock urls are correct we display them.
 
543
        # We avoid displaying remote lock urls.
 
544
        lock_url = self.transport.abspath(self.path)
 
545
        if lock_url.startswith('file://'):
 
546
            lock_url = lock_url.split('.bzr/')[0]
 
547
        else:
 
548
            lock_url = ''
 
549
        return lock_url
 
550
 
 
551
    def wait_lock(self, timeout=None, poll=None, max_attempts=None):
365
552
        """Wait a certain period for a lock.
366
553
 
367
554
        If the lock can be acquired within the bounded time, it
369
556
        is raised.  Either way, this function should return within
370
557
        approximately `timeout` seconds.  (It may be a bit more if
371
558
        a transport operation takes a long time to complete.)
 
559
 
 
560
        :param timeout: Approximate maximum amount of time to wait for the
 
561
        lock, in seconds.
 
562
 
 
563
        :param poll: Delay in seconds between retrying the lock.
 
564
 
 
565
        :param max_attempts: Maximum number of times to try to lock.
 
566
 
 
567
        :return: The lock token.
372
568
        """
373
569
        if timeout is None:
374
570
            timeout = _DEFAULT_TIMEOUT_SECONDS
375
571
        if poll is None:
376
572
            poll = _DEFAULT_POLL_SECONDS
377
 
 
378
 
        # XXX: the transport interface doesn't let us guard 
379
 
        # against operations there taking a long time.
 
573
        # XXX: the transport interface doesn't let us guard against operations
 
574
        # there taking a long time, so the total elapsed time or poll interval
 
575
        # may be more than was requested.
380
576
        deadline = time.time() + timeout
381
577
        deadline_str = None
382
578
        last_info = None
 
579
        attempt_count = 0
 
580
        lock_url = self.lock_url_for_display()
383
581
        while True:
 
582
            attempt_count += 1
384
583
            try:
385
 
                self.attempt_lock()
386
 
                return
 
584
                return self.attempt_lock()
387
585
            except LockContention:
 
586
                # possibly report the blockage, then try again
388
587
                pass
 
588
            # TODO: In a few cases, we find out that there's contention by
 
589
            # reading the held info and observing that it's not ours.  In
 
590
            # those cases it's a bit redundant to read it again.  However,
 
591
            # the normal case (??) is that the rename fails and so we
 
592
            # don't know who holds the lock.  For simplicity we peek
 
593
            # always.
389
594
            new_info = self.peek()
390
 
            mutter('last_info: %s, new info: %s', last_info, new_info)
391
595
            if new_info is not None and new_info != last_info:
392
596
                if last_info is None:
393
597
                    start = 'Unable to obtain'
398
602
                if deadline_str is None:
399
603
                    deadline_str = time.strftime('%H:%M:%S',
400
604
                                                 time.localtime(deadline))
401
 
                self._report_function('%s %s\n'
402
 
                                      '%s\n' # held by
403
 
                                      '%s\n' # locked ... ago
404
 
                                      'Will continue to try until %s\n',
405
 
                                      start,
406
 
                                      formatted_info[0],
407
 
                                      formatted_info[1],
408
 
                                      formatted_info[2],
409
 
                                      deadline_str)
410
 
 
 
605
                user, hostname, pid, time_ago = formatted_info
 
606
                msg = ('%s lock %s '        # lock_url
 
607
                    'held by '              # start
 
608
                    '%s\n'                  # user
 
609
                    'at %s '                # hostname
 
610
                    '[process #%s], '       # pid
 
611
                    'acquired %s.')         # time ago
 
612
                msg_args = [start, lock_url, user, hostname, pid, time_ago]
 
613
                if timeout > 0:
 
614
                    msg += ('\nWill continue to try until %s, unless '
 
615
                        'you press Ctrl-C.')
 
616
                    msg_args.append(deadline_str)
 
617
                msg += '\nSee "bzr help break-lock" for more.'
 
618
                self._report_function(msg, *msg_args)
 
619
            if (max_attempts is not None) and (attempt_count >= max_attempts):
 
620
                self._trace("exceeded %d attempts")
 
621
                raise LockContention(self)
411
622
            if time.time() + poll < deadline:
 
623
                self._trace("waiting %ss", poll)
412
624
                time.sleep(poll)
413
625
            else:
414
 
                raise LockContention(self)
415
 
 
416
 
    def lock_write(self):
417
 
        """Wait for and acquire the lock."""
418
 
        self.wait_lock()
 
626
                # As timeout is always 0 for remote locks
 
627
                # this block is applicable only for local
 
628
                # lock contention
 
629
                self._trace("timeout after waiting %ss", timeout)
 
630
                raise LockContention('(local)', lock_url)
 
631
 
 
632
    def leave_in_place(self):
 
633
        self._locked_via_token = True
 
634
 
 
635
    def dont_leave_in_place(self):
 
636
        self._locked_via_token = False
 
637
 
 
638
    def lock_write(self, token=None):
 
639
        """Wait for and acquire the lock.
 
640
 
 
641
        :param token: if this is already locked, then lock_write will fail
 
642
            unless the token matches the existing lock.
 
643
        :returns: a token if this instance supports tokens, otherwise None.
 
644
        :raises TokenLockingNotSupported: when a token is given but this
 
645
            instance doesn't support using token locks.
 
646
        :raises MismatchedToken: if the specified token doesn't match the token
 
647
            of the existing lock.
 
648
 
 
649
        A token should be passed in if you know that you have locked the object
 
650
        some other way, and need to synchronise this object's state with that
 
651
        fact.
 
652
 
 
653
        XXX: docstring duplicated from LockableFiles.lock_write.
 
654
        """
 
655
        if token is not None:
 
656
            self.validate_token(token)
 
657
            self.nonce = token
 
658
            self._lock_held = True
 
659
            self._locked_via_token = True
 
660
            return token
 
661
        else:
 
662
            return self.wait_lock()
419
663
 
420
664
    def lock_read(self):
421
665
        """Compatibility-mode shared lock.
422
666
 
423
 
        LockDir doesn't support shared read-only locks, so this 
 
667
        LockDir doesn't support shared read-only locks, so this
424
668
        just pretends that the lock is taken but really does nothing.
425
669
        """
426
 
        # At the moment Branches are commonly locked for read, but 
 
670
        # At the moment Branches are commonly locked for read, but
427
671
        # we can't rely on that remotely.  Once this is cleaned up,
428
 
        # reenable this warning to prevent it coming back in 
 
672
        # reenable this warning to prevent it coming back in
429
673
        # -- mbp 20060303
430
674
        ## warn("LockDir.lock_read falls back to write lock")
431
675
        if self._lock_held or self._fake_read_lock:
432
676
            raise LockContention(self)
433
677
        self._fake_read_lock = True
434
678
 
435
 
    def wait(self, timeout=20, poll=0.5):
436
 
        """Wait a certain period for a lock to be released."""
437
 
        # XXX: the transport interface doesn't let us guard 
438
 
        # against operations there taking a long time.
439
 
        deadline = time.time() + timeout
440
 
        while True:
441
 
            if self.peek():
442
 
                return
443
 
            if time.time() + poll < deadline:
444
 
                time.sleep(poll)
445
 
            else:
446
 
                raise LockContention(self)
447
 
 
448
679
    def _format_lock_info(self, info):
449
680
        """Turn the contents of peek() into something for the user"""
450
 
        lock_url = self.transport.abspath(self.path)
451
 
        delta = time.time() - int(info['start_time'])
 
681
        start_time = info.get('start_time')
 
682
        if start_time is None:
 
683
            time_ago = '(unknown)'
 
684
        else:
 
685
            time_ago = format_delta(time.time() - int(info['start_time']))
 
686
        user = info.get('user', '<unknown>')
 
687
        hostname = info.get('hostname', '<unknown>')
 
688
        pid = info.get('pid', '<unknown>')
452
689
        return [
453
 
            'lock %s' % (lock_url,),
454
 
            'held by %(user)s on host %(hostname)s [process #%(pid)s]' % info,
455
 
            'locked %s' % (format_delta(delta),),
 
690
            user,
 
691
            hostname,
 
692
            pid,
 
693
            time_ago,
456
694
            ]
457
695
 
 
696
    def validate_token(self, token):
 
697
        if token is not None:
 
698
            info = self.peek()
 
699
            if info is None:
 
700
                # Lock isn't held
 
701
                lock_token = None
 
702
            else:
 
703
                lock_token = info.get('nonce')
 
704
            if token != lock_token:
 
705
                raise errors.TokenMismatch(token, lock_token)
 
706
            else:
 
707
                self._trace("revalidated by token %r", token)
 
708
 
 
709
    def _trace(self, format, *args):
 
710
        if 'lock' not in debug.debug_flags:
 
711
            return
 
712
        mutter(str(self) + ": " + (format % args))