← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/lockdir.py

  • Committer: Launchpad Translations on behalf of bzr-core
  • Date: 2012-05-29 04:30:47 UTC
  • mto: (6581.1.1 trunk)
  • mto: This revision was merged to the branch mainline in revision 6582.
  • Revision ID: launchpad_translations_on_behalf_of_bzr-core-20120529043047-mmj2hkq63ke8kl81
Launchpad automatic translations update.

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
Some classes of stale locks can be predicted by checking: the host name is the
 
96
same as the local host name; the user name is the same as the local user; the
 
97
process id no longer exists.  The check on user name is not strictly necessary
 
98
but helps protect against colliding host names.
95
99
"""
96
100
 
 
101
from __future__ import absolute_import
 
102
 
 
103
 
 
104
# TODO: We sometimes have the problem that our attempt to rename '1234' to
 
105
# 'held' fails because the transport server moves into an existing directory,
 
106
# rather than failing the rename.  If we made the info file name the same as
 
107
# the locked directory name we would avoid this problem because moving into
 
108
# the held directory would implicitly clash.  However this would not mesh with
 
109
# the existing locking code and needs a new format of the containing object.
 
110
# -- robertc, mbp 20070628
 
111
 
97
112
import os
98
113
import time
99
 
from StringIO import StringIO
100
114
 
101
 
import bzrlib.config
 
115
from bzrlib import (
 
116
    config,
 
117
    debug,
 
118
    errors,
 
119
    lock,
 
120
    osutils,
 
121
    ui,
 
122
    urlutils,
 
123
    )
 
124
from bzrlib.decorators import only_raises
102
125
from bzrlib.errors import (
103
126
        DirectoryNotEmpty,
104
127
        FileExists,
105
128
        LockBreakMismatch,
106
129
        LockBroken,
107
130
        LockContention,
 
131
        LockCorrupt,
 
132
        LockFailed,
108
133
        LockNotHeld,
109
134
        NoSuchFile,
110
135
        PathError,
111
136
        ResourceBusy,
112
 
        UnlockableTransport,
 
137
        TransportError,
113
138
        )
114
 
from bzrlib.trace import mutter
115
 
from bzrlib.transport import Transport
116
 
from bzrlib.osutils import rand_chars
117
 
from bzrlib.rio import RioWriter, read_stanza, Stanza
 
139
from bzrlib.trace import mutter, note
 
140
from bzrlib.osutils import format_delta, rand_chars, get_host_name
 
141
from bzrlib.i18n import gettext
 
142
 
 
143
from bzrlib.lazy_import import lazy_import
 
144
lazy_import(globals(), """
 
145
from bzrlib import rio
 
146
""")
118
147
 
119
148
# XXX: At the moment there is no consideration of thread safety on LockDir
120
149
# objects.  This should perhaps be updated - e.g. if two threads try to take a
130
159
# TODO: Make sure to pass the right file and directory mode bits to all
131
160
# files/dirs created.
132
161
 
133
 
_DEFAULT_TIMEOUT_SECONDS = 300
134
 
_DEFAULT_POLL_SECONDS = 0.5
135
 
 
136
 
class LockDir(object):
137
 
    """Write-lock guarding access to data."""
 
162
 
 
163
_DEFAULT_TIMEOUT_SECONDS = 30
 
164
_DEFAULT_POLL_SECONDS = 1.0
 
165
 
 
166
 
 
167
class LockDir(lock.Lock):
 
168
    """Write-lock guarding access to data.
 
169
    """
138
170
 
139
171
    __INFO_NAME = '/info'
140
172
 
141
 
    def __init__(self, transport, path, file_modebits=0644, dir_modebits=0755):
 
173
    def __init__(self, transport, path, file_modebits=0644, dir_modebits=0755,
 
174
        extra_holder_info=None):
142
175
        """Create a new LockDir object.
143
176
 
144
177
        The LockDir is initially unlocked - this just creates the object.
145
178
 
146
179
        :param transport: Transport which will contain the lock
147
180
 
148
 
        :param path: Path to the lock within the base directory of the 
 
181
        :param path: Path to the lock within the base directory of the
149
182
            transport.
 
183
 
 
184
        :param extra_holder_info: If passed, {str:str} dict of extra or
 
185
            updated information to insert into the info file when the lock is
 
186
            taken.
150
187
        """
151
 
        assert isinstance(transport, Transport), \
152
 
            ("not a transport: %r" % transport)
153
188
        self.transport = transport
154
189
        self.path = path
155
190
        self._lock_held = False
 
191
        self._locked_via_token = False
156
192
        self._fake_read_lock = False
157
193
        self._held_dir = path + '/held'
158
194
        self._held_info_path = self._held_dir + self.__INFO_NAME
159
195
        self._file_modebits = file_modebits
160
196
        self._dir_modebits = dir_modebits
161
 
        self.nonce = rand_chars(20)
 
197
        self._report_function = note
 
198
        self.extra_holder_info = extra_holder_info
 
199
        self._warned_about_lock_holder = None
162
200
 
163
201
    def __repr__(self):
164
202
        return '%s(%s%s)' % (self.__class__.__name__,
170
208
    def create(self, mode=None):
171
209
        """Create the on-disk lock.
172
210
 
173
 
        This is typically only called when the object/directory containing the 
 
211
        This is typically only called when the object/directory containing the
174
212
        directory is first created.  The lock is not held when it's created.
175
213
        """
176
 
        if self.transport.is_readonly():
177
 
            raise UnlockableTransport(self.transport)
178
 
        self.transport.mkdir(self.path, mode=mode)
179
 
 
180
 
    def attempt_lock(self):
181
 
        """Take the lock; fail if it's already held.
182
 
        
183
 
        If you wish to block until the lock can be obtained, call wait_lock()
184
 
        instead.
185
 
        """
186
 
        if self._fake_read_lock:
187
 
            raise LockContention(self)
188
 
        if self.transport.is_readonly():
189
 
            raise UnlockableTransport(self.transport)
190
 
        try:
191
 
            tmpname = '%s/pending.%s.tmp' % (self.path, rand_chars(20))
192
 
            self.transport.mkdir(tmpname)
193
 
            sio = StringIO()
194
 
            self._prepare_info(sio)
195
 
            sio.seek(0)
196
 
            # append will create a new file; we use append rather than put
197
 
            # because we don't want to write to a temporary file and rename
198
 
            # into place, because that's going to happen to the whole
199
 
            # directory
200
 
            self.transport.append(tmpname + self.__INFO_NAME, sio)
201
 
            self.transport.rename(tmpname, self._held_dir)
202
 
            self._lock_held = True
203
 
            self.confirm()
204
 
        except (PathError, DirectoryNotEmpty, FileExists, ResourceBusy), e:
205
 
            mutter("contention on %r: %s", self, e)
206
 
            raise LockContention(self)
207
 
 
 
214
        self._trace("create lock directory")
 
215
        try:
 
216
            self.transport.mkdir(self.path, mode=mode)
 
217
        except (TransportError, PathError), e:
 
218
            raise LockFailed(self, e)
 
219
 
 
220
    def _attempt_lock(self):
 
221
        """Make the pending directory and attempt to rename into place.
 
222
 
 
223
        If the rename succeeds, we read back the info file to check that we
 
224
        really got the lock.
 
225
 
 
226
        If we fail to acquire the lock, this method is responsible for
 
227
        cleaning up the pending directory if possible.  (But it doesn't do
 
228
        that yet.)
 
229
 
 
230
        :returns: The nonce of the lock, if it was successfully acquired.
 
231
 
 
232
        :raises LockContention: If the lock is held by someone else.  The
 
233
            exception contains the info of the current holder of the lock.
 
234
        """
 
235
        self._trace("lock_write...")
 
236
        start_time = time.time()
 
237
        try:
 
238
            tmpname = self._create_pending_dir()
 
239
        except (errors.TransportError, PathError), e:
 
240
            self._trace("... failed to create pending dir, %s", e)
 
241
            raise LockFailed(self, e)
 
242
        while True:
 
243
            try:
 
244
                self.transport.rename(tmpname, self._held_dir)
 
245
                break
 
246
            except (errors.TransportError, PathError, DirectoryNotEmpty,
 
247
                    FileExists, ResourceBusy), e:
 
248
                self._trace("... contention, %s", e)
 
249
                other_holder = self.peek()
 
250
                self._trace("other holder is %r" % other_holder)
 
251
                try:
 
252
                    self._handle_lock_contention(other_holder)
 
253
                except:
 
254
                    self._remove_pending_dir(tmpname)
 
255
                    raise
 
256
            except Exception, e:
 
257
                self._trace("... lock failed, %s", e)
 
258
                self._remove_pending_dir(tmpname)
 
259
                raise
 
260
        # We must check we really got the lock, because Launchpad's sftp
 
261
        # server at one time had a bug were the rename would successfully
 
262
        # move the new directory into the existing directory, which was
 
263
        # incorrect.  It's possible some other servers or filesystems will
 
264
        # have a similar bug allowing someone to think they got the lock
 
265
        # when it's already held.
 
266
        #
 
267
        # See <https://bugs.launchpad.net/bzr/+bug/498378> for one case.
 
268
        #
 
269
        # Strictly the check is unnecessary and a waste of time for most
 
270
        # people, but probably worth trapping if something is wrong.
 
271
        info = self.peek()
 
272
        self._trace("after locking, info=%r", info)
 
273
        if info is None:
 
274
            raise LockFailed(self, "lock was renamed into place, but "
 
275
                "now is missing!")
 
276
        if info.get('nonce') != self.nonce:
 
277
            self._trace("rename succeeded, "
 
278
                "but lock is still held by someone else")
 
279
            raise LockContention(self)
 
280
        self._lock_held = True
 
281
        self._trace("... lock succeeded after %dms",
 
282
                (time.time() - start_time) * 1000)
 
283
        return self.nonce
 
284
 
 
285
    def _handle_lock_contention(self, other_holder):
 
286
        """A lock we want to take is held by someone else.
 
287
 
 
288
        This function can: tell the user about it; possibly detect that it's
 
289
        safe or appropriate to steal the lock, or just raise an exception.
 
290
 
 
291
        If this function returns (without raising an exception) the lock will
 
292
        be attempted again.
 
293
 
 
294
        :param other_holder: A LockHeldInfo for the current holder; note that
 
295
            it might be None if the lock can be seen to be held but the info
 
296
            can't be read.
 
297
        """
 
298
        if (other_holder is not None):
 
299
            if other_holder.is_lock_holder_known_dead():
 
300
                if self.get_config().get('locks.steal_dead'):
 
301
                    ui.ui_factory.show_user_warning(
 
302
                        'locks_steal_dead',
 
303
                        lock_url=urlutils.join(self.transport.base, self.path),
 
304
                        other_holder_info=unicode(other_holder))
 
305
                    self.force_break(other_holder)
 
306
                    self._trace("stole lock from dead holder")
 
307
                    return
 
308
        raise LockContention(self)
 
309
 
 
310
    def _remove_pending_dir(self, tmpname):
 
311
        """Remove the pending directory
 
312
 
 
313
        This is called if we failed to rename into place, so that the pending
 
314
        dirs don't clutter up the lockdir.
 
315
        """
 
316
        self._trace("remove %s", tmpname)
 
317
        try:
 
318
            self.transport.delete(tmpname + self.__INFO_NAME)
 
319
            self.transport.rmdir(tmpname)
 
320
        except PathError, e:
 
321
            note(gettext("error removing pending lock: %s"), e)
 
322
 
 
323
    def _create_pending_dir(self):
 
324
        tmpname = '%s/%s.tmp' % (self.path, rand_chars(10))
 
325
        try:
 
326
            self.transport.mkdir(tmpname)
 
327
        except NoSuchFile:
 
328
            # This may raise a FileExists exception
 
329
            # which is okay, it will be caught later and determined
 
330
            # to be a LockContention.
 
331
            self._trace("lock directory does not exist, creating it")
 
332
            self.create(mode=self._dir_modebits)
 
333
            # After creating the lock directory, try again
 
334
            self.transport.mkdir(tmpname)
 
335
        info = LockHeldInfo.for_this_process(self.extra_holder_info)
 
336
        self.nonce = info.get('nonce')
 
337
        # We use put_file_non_atomic because we just created a new unique
 
338
        # directory so we don't have to worry about files existing there.
 
339
        # We'll rename the whole directory into place to get atomic
 
340
        # properties
 
341
        self.transport.put_bytes_non_atomic(tmpname + self.__INFO_NAME,
 
342
            info.to_bytes())
 
343
        return tmpname
 
344
 
 
345
    @only_raises(LockNotHeld, LockBroken)
208
346
    def unlock(self):
209
347
        """Release a held lock
210
348
        """
212
350
            self._fake_read_lock = False
213
351
            return
214
352
        if not self._lock_held:
215
 
            raise LockNotHeld(self)
216
 
        # rename before deleting, because we can't atomically remove the whole
217
 
        # tree
218
 
        tmpname = '%s/releasing.%s.tmp' % (self.path, rand_chars(20))
219
 
        # gotta own it to unlock
220
 
        self.confirm()
221
 
        self.transport.rename(self._held_dir, tmpname)
222
 
        self._lock_held = False
223
 
        self.transport.delete(tmpname + self.__INFO_NAME)
224
 
        self.transport.rmdir(tmpname)
 
353
            return lock.cant_unlock_not_held(self)
 
354
        if self._locked_via_token:
 
355
            self._locked_via_token = False
 
356
            self._lock_held = False
 
357
        else:
 
358
            old_nonce = self.nonce
 
359
            # rename before deleting, because we can't atomically remove the
 
360
            # whole tree
 
361
            start_time = time.time()
 
362
            self._trace("unlocking")
 
363
            tmpname = '%s/releasing.%s.tmp' % (self.path, rand_chars(20))
 
364
            # gotta own it to unlock
 
365
            self.confirm()
 
366
            self.transport.rename(self._held_dir, tmpname)
 
367
            self._lock_held = False
 
368
            self.transport.delete(tmpname + self.__INFO_NAME)
 
369
            try:
 
370
                self.transport.rmdir(tmpname)
 
371
            except DirectoryNotEmpty, e:
 
372
                # There might have been junk left over by a rename that moved
 
373
                # another locker within the 'held' directory.  do a slower
 
374
                # deletion where we list the directory and remove everything
 
375
                # within it.
 
376
                #
 
377
                # Maybe this should be broader to allow for ftp servers with
 
378
                # non-specific error messages?
 
379
                self._trace("doing recursive deletion of non-empty directory "
 
380
                        "%s", tmpname)
 
381
                self.transport.delete_tree(tmpname)
 
382
            self._trace("... unlock succeeded after %dms",
 
383
                    (time.time() - start_time) * 1000)
 
384
            result = lock.LockResult(self.transport.abspath(self.path),
 
385
                                     old_nonce)
 
386
            for hook in self.hooks['lock_released']:
 
387
                hook(result)
225
388
 
226
389
    def break_lock(self):
227
390
        """Break a lock not held by this instance of LockDir.
228
391
 
229
 
        This is a UI centric function: it uses the bzrlib.ui.ui_factory to
 
392
        This is a UI centric function: it uses the ui.ui_factory to
230
393
        prompt for input if a lock is detected and there is any doubt about
231
 
        it possibly being still active.
 
394
        it possibly being still active.  force_break is the non-interactive
 
395
        version.
 
396
 
 
397
        :returns: LockResult for the broken lock.
232
398
        """
233
399
        self._check_not_locked()
234
 
        holder_info = self.peek()
 
400
        try:
 
401
            holder_info = self.peek()
 
402
        except LockCorrupt, e:
 
403
            # The lock info is corrupt.
 
404
            if ui.ui_factory.get_boolean(u"Break (corrupt %r)" % (self,)):
 
405
                self.force_break_corrupt(e.file_data)
 
406
            return
235
407
        if holder_info is not None:
236
 
            if bzrlib.ui.ui_factory.get_boolean(
237
 
                "Break lock %s held by %s@%s [process #%s]" % (
238
 
                    self.transport,
239
 
                    holder_info["user"],
240
 
                    holder_info["hostname"],
241
 
                    holder_info["pid"])):
242
 
                self.force_break(holder_info)
243
 
        
 
408
            if ui.ui_factory.confirm_action(
 
409
                u"Break %(lock_info)s",
 
410
                'bzrlib.lockdir.break',
 
411
                dict(lock_info=unicode(holder_info))):
 
412
                result = self.force_break(holder_info)
 
413
                ui.ui_factory.show_message(
 
414
                    "Broke lock %s" % result.lock_url)
 
415
 
244
416
    def force_break(self, dead_holder_info):
245
417
        """Release a lock held by another process.
246
418
 
248
420
        it still thinks it has the lock there will be two concurrent writers.
249
421
        In general the user's approval should be sought for lock breaks.
250
422
 
251
 
        dead_holder_info must be the result of a previous LockDir.peek() call;
252
 
        this is used to check that it's still held by the same process that
253
 
        the user decided was dead.  If this is not the current holder,
254
 
        LockBreakMismatch is raised.
255
 
 
256
423
        After the lock is broken it will not be held by any process.
257
 
        It is possible that another process may sneak in and take the 
 
424
        It is possible that another process may sneak in and take the
258
425
        lock before the breaking process acquires it.
 
426
 
 
427
        :param dead_holder_info:
 
428
            Must be the result of a previous LockDir.peek() call; this is used
 
429
            to check that it's still held by the same process that the user
 
430
            decided was dead.  If this is not the current holder,
 
431
            LockBreakMismatch is raised.
 
432
 
 
433
        :returns: LockResult for the broken lock.
259
434
        """
260
 
        if not isinstance(dead_holder_info, dict):
 
435
        if not isinstance(dead_holder_info, LockHeldInfo):
261
436
            raise ValueError("dead_holder_info: %r" % dead_holder_info)
262
437
        self._check_not_locked()
263
438
        current_info = self.peek()
269
444
        tmpname = '%s/broken.%s.tmp' % (self.path, rand_chars(20))
270
445
        self.transport.rename(self._held_dir, tmpname)
271
446
        # check that we actually broke the right lock, not someone else;
272
 
        # there's a small race window between checking it and doing the 
 
447
        # there's a small race window between checking it and doing the
273
448
        # rename.
274
449
        broken_info_path = tmpname + self.__INFO_NAME
275
450
        broken_info = self._read_info_file(broken_info_path)
277
452
            raise LockBreakMismatch(self, broken_info, dead_holder_info)
278
453
        self.transport.delete(broken_info_path)
279
454
        self.transport.rmdir(tmpname)
 
455
        result = lock.LockResult(self.transport.abspath(self.path),
 
456
                                 current_info.get('nonce'))
 
457
        for hook in self.hooks['lock_broken']:
 
458
            hook(result)
 
459
        return result
 
460
 
 
461
    def force_break_corrupt(self, corrupt_info_lines):
 
462
        """Release a lock that has been corrupted.
 
463
 
 
464
        This is very similar to force_break, it except it doesn't assume that
 
465
        self.peek() can work.
 
466
 
 
467
        :param corrupt_info_lines: the lines of the corrupted info file, used
 
468
            to check that the lock hasn't changed between reading the (corrupt)
 
469
            info file and calling force_break_corrupt.
 
470
        """
 
471
        # XXX: this copes with unparseable info files, but what about missing
 
472
        # info files?  Or missing lock dirs?
 
473
        self._check_not_locked()
 
474
        tmpname = '%s/broken.%s.tmp' % (self.path, rand_chars(20))
 
475
        self.transport.rename(self._held_dir, tmpname)
 
476
        # check that we actually broke the right lock, not someone else;
 
477
        # there's a small race window between checking it and doing the
 
478
        # rename.
 
479
        broken_info_path = tmpname + self.__INFO_NAME
 
480
        broken_content = self.transport.get_bytes(broken_info_path)
 
481
        broken_lines = osutils.split_lines(broken_content)
 
482
        if broken_lines != corrupt_info_lines:
 
483
            raise LockBreakMismatch(self, broken_lines, corrupt_info_lines)
 
484
        self.transport.delete(broken_info_path)
 
485
        self.transport.rmdir(tmpname)
 
486
        result = lock.LockResult(self.transport.abspath(self.path))
 
487
        for hook in self.hooks['lock_broken']:
 
488
            hook(result)
280
489
 
281
490
    def _check_not_locked(self):
282
491
        """If the lock is held by this instance, raise an error."""
290
499
        or if the lock has been affected by a bug.
291
500
 
292
501
        If the lock is not thought to be held, raises LockNotHeld.  If
293
 
        the lock is thought to be held but has been broken, raises 
 
502
        the lock is thought to be held but has been broken, raises
294
503
        LockBroken.
295
504
        """
296
505
        if not self._lock_held:
302
511
        if info.get('nonce') != self.nonce:
303
512
            # there is a lock, but not ours
304
513
            raise LockBroken(self)
305
 
        
 
514
 
306
515
    def _read_info_file(self, path):
307
516
        """Read one given info file.
308
517
 
309
518
        peek() reads the info file of the lock holder, if any.
310
519
        """
311
 
        return self._parse_info(self.transport.get(path))
 
520
        return LockHeldInfo.from_info_file_bytes(
 
521
            self.transport.get_bytes(path))
312
522
 
313
523
    def peek(self):
314
524
        """Check if the lock is held by anyone.
315
 
        
316
 
        If it is held, this returns the lock info structure as a rio Stanza,
 
525
 
 
526
        If it is held, this returns the lock info structure as a dict
317
527
        which contains some information about the current lock holder.
318
528
        Otherwise returns None.
319
529
        """
320
530
        try:
321
531
            info = self._read_info_file(self._held_info_path)
322
 
            assert isinstance(info, dict), \
323
 
                    "bad parse result %r" % info
 
532
            self._trace("peek -> held")
324
533
            return info
325
534
        except NoSuchFile, e:
326
 
            return None
 
535
            self._trace("peek -> not held")
327
536
 
328
 
    def _prepare_info(self, outf):
 
537
    def _prepare_info(self):
329
538
        """Write information about a pending lock to a temporary file.
330
539
        """
331
 
        import socket
332
 
        # XXX: is creating this here inefficient?
333
 
        config = bzrlib.config.GlobalConfig()
334
 
        s = Stanza(hostname=socket.gethostname(),
335
 
                   pid=str(os.getpid()),
336
 
                   start_time=str(int(time.time())),
337
 
                   nonce=self.nonce,
338
 
                   user=config.user_email(),
339
 
                   )
340
 
        RioWriter(outf).write_stanza(s)
341
 
 
342
 
    def _parse_info(self, info_file):
343
 
        return read_stanza(info_file.readlines()).as_dict()
344
 
 
345
 
    def wait_lock(self, timeout=_DEFAULT_TIMEOUT_SECONDS,
346
 
                  poll=_DEFAULT_POLL_SECONDS):
 
540
 
 
541
    def attempt_lock(self):
 
542
        """Take the lock; fail if it's already held.
 
543
 
 
544
        If you wish to block until the lock can be obtained, call wait_lock()
 
545
        instead.
 
546
 
 
547
        :return: The lock token.
 
548
        :raises LockContention: if the lock is held by someone else.
 
549
        """
 
550
        if self._fake_read_lock:
 
551
            raise LockContention(self)
 
552
        result = self._attempt_lock()
 
553
        hook_result = lock.LockResult(self.transport.abspath(self.path),
 
554
                self.nonce)
 
555
        for hook in self.hooks['lock_acquired']:
 
556
            hook(hook_result)
 
557
        return result
 
558
 
 
559
    def lock_url_for_display(self):
 
560
        """Give a nicely-printable representation of the URL of this lock."""
 
561
        # As local lock urls are correct we display them.
 
562
        # We avoid displaying remote lock urls.
 
563
        lock_url = self.transport.abspath(self.path)
 
564
        if lock_url.startswith('file://'):
 
565
            lock_url = lock_url.split('.bzr/')[0]
 
566
        else:
 
567
            lock_url = ''
 
568
        return lock_url
 
569
 
 
570
    def wait_lock(self, timeout=None, poll=None, max_attempts=None):
347
571
        """Wait a certain period for a lock.
348
572
 
349
573
        If the lock can be acquired within the bounded time, it
351
575
        is raised.  Either way, this function should return within
352
576
        approximately `timeout` seconds.  (It may be a bit more if
353
577
        a transport operation takes a long time to complete.)
 
578
 
 
579
        :param timeout: Approximate maximum amount of time to wait for the
 
580
        lock, in seconds.
 
581
 
 
582
        :param poll: Delay in seconds between retrying the lock.
 
583
 
 
584
        :param max_attempts: Maximum number of times to try to lock.
 
585
 
 
586
        :return: The lock token.
354
587
        """
355
 
        # XXX: the transport interface doesn't let us guard 
356
 
        # against operations there taking a long time.
 
588
        if timeout is None:
 
589
            timeout = _DEFAULT_TIMEOUT_SECONDS
 
590
        if poll is None:
 
591
            poll = _DEFAULT_POLL_SECONDS
 
592
        # XXX: the transport interface doesn't let us guard against operations
 
593
        # there taking a long time, so the total elapsed time or poll interval
 
594
        # may be more than was requested.
357
595
        deadline = time.time() + timeout
 
596
        deadline_str = None
 
597
        last_info = None
 
598
        attempt_count = 0
 
599
        lock_url = self.lock_url_for_display()
358
600
        while True:
 
601
            attempt_count += 1
359
602
            try:
360
 
                self.attempt_lock()
361
 
                return
 
603
                return self.attempt_lock()
362
604
            except LockContention:
 
605
                # possibly report the blockage, then try again
363
606
                pass
 
607
            # TODO: In a few cases, we find out that there's contention by
 
608
            # reading the held info and observing that it's not ours.  In
 
609
            # those cases it's a bit redundant to read it again.  However,
 
610
            # the normal case (??) is that the rename fails and so we
 
611
            # don't know who holds the lock.  For simplicity we peek
 
612
            # always.
 
613
            new_info = self.peek()
 
614
            if new_info is not None and new_info != last_info:
 
615
                if last_info is None:
 
616
                    start = gettext('Unable to obtain')
 
617
                else:
 
618
                    start = gettext('Lock owner changed for')
 
619
                last_info = new_info
 
620
                msg = gettext('{0} lock {1} {2}.').format(start, lock_url,
 
621
                                                                    new_info)
 
622
                if deadline_str is None:
 
623
                    deadline_str = time.strftime('%H:%M:%S',
 
624
                                                    time.localtime(deadline))
 
625
                if timeout > 0:
 
626
                    msg += '\n' + gettext(
 
627
                             'Will continue to try until %s, unless '
 
628
                             'you press Ctrl-C.') % deadline_str
 
629
                msg += '\n' + gettext('See "bzr help break-lock" for more.')
 
630
                self._report_function(msg)
 
631
            if (max_attempts is not None) and (attempt_count >= max_attempts):
 
632
                self._trace("exceeded %d attempts")
 
633
                raise LockContention(self)
364
634
            if time.time() + poll < deadline:
 
635
                self._trace("waiting %ss", poll)
365
636
                time.sleep(poll)
366
637
            else:
367
 
                raise LockContention(self)
368
 
 
369
 
    def lock_write(self):
370
 
        """Wait for and acquire the lock."""
371
 
        self.attempt_lock()
 
638
                # As timeout is always 0 for remote locks
 
639
                # this block is applicable only for local
 
640
                # lock contention
 
641
                self._trace("timeout after waiting %ss", timeout)
 
642
                raise LockContention('(local)', lock_url)
 
643
 
 
644
    def leave_in_place(self):
 
645
        self._locked_via_token = True
 
646
 
 
647
    def dont_leave_in_place(self):
 
648
        self._locked_via_token = False
 
649
 
 
650
    def lock_write(self, token=None):
 
651
        """Wait for and acquire the lock.
 
652
 
 
653
        :param token: if this is already locked, then lock_write will fail
 
654
            unless the token matches the existing lock.
 
655
        :returns: a token if this instance supports tokens, otherwise None.
 
656
        :raises TokenLockingNotSupported: when a token is given but this
 
657
            instance doesn't support using token locks.
 
658
        :raises MismatchedToken: if the specified token doesn't match the token
 
659
            of the existing lock.
 
660
 
 
661
        A token should be passed in if you know that you have locked the object
 
662
        some other way, and need to synchronise this object's state with that
 
663
        fact.
 
664
 
 
665
        XXX: docstring duplicated from LockableFiles.lock_write.
 
666
        """
 
667
        if token is not None:
 
668
            self.validate_token(token)
 
669
            self.nonce = token
 
670
            self._lock_held = True
 
671
            self._locked_via_token = True
 
672
            return token
 
673
        else:
 
674
            return self.wait_lock()
372
675
 
373
676
    def lock_read(self):
374
677
        """Compatibility-mode shared lock.
375
678
 
376
 
        LockDir doesn't support shared read-only locks, so this 
 
679
        LockDir doesn't support shared read-only locks, so this
377
680
        just pretends that the lock is taken but really does nothing.
378
681
        """
379
 
        # At the moment Branches are commonly locked for read, but 
 
682
        # At the moment Branches are commonly locked for read, but
380
683
        # we can't rely on that remotely.  Once this is cleaned up,
381
 
        # reenable this warning to prevent it coming back in 
 
684
        # reenable this warning to prevent it coming back in
382
685
        # -- mbp 20060303
383
686
        ## warn("LockDir.lock_read falls back to write lock")
384
687
        if self._lock_held or self._fake_read_lock:
385
688
            raise LockContention(self)
386
689
        self._fake_read_lock = True
387
690
 
388
 
    def wait(self, timeout=20, poll=0.5):
389
 
        """Wait a certain period for a lock to be released."""
390
 
        # XXX: the transport interface doesn't let us guard 
391
 
        # against operations there taking a long time.
392
 
        deadline = time.time() + timeout
393
 
        while True:
394
 
            if self.peek():
395
 
                return
396
 
            if time.time() + poll < deadline:
397
 
                time.sleep(poll)
398
 
            else:
399
 
                raise LockContention(self)
400
 
 
 
691
    def validate_token(self, token):
 
692
        if token is not None:
 
693
            info = self.peek()
 
694
            if info is None:
 
695
                # Lock isn't held
 
696
                lock_token = None
 
697
            else:
 
698
                lock_token = info.get('nonce')
 
699
            if token != lock_token:
 
700
                raise errors.TokenMismatch(token, lock_token)
 
701
            else:
 
702
                self._trace("revalidated by token %r", token)
 
703
 
 
704
    def _trace(self, format, *args):
 
705
        if 'lock' not in debug.debug_flags:
 
706
            return
 
707
        mutter(str(self) + ": " + (format % args))
 
708
 
 
709
    def get_config(self):
 
710
        """Get the configuration that governs this lockdir."""
 
711
        # XXX: This really should also use the locationconfig at least, but
 
712
        # that seems a bit hard to hook up at the moment. -- mbp 20110329
 
713
        # FIXME: The above is still true ;) -- vila 20110811
 
714
        return config.GlobalStack()
 
715
 
 
716
 
 
717
class LockHeldInfo(object):
 
718
    """The information recorded about a held lock.
 
719
 
 
720
    This information is recorded into the lock when it's taken, and it can be
 
721
    read back by any process with access to the lockdir.  It can be used, for
 
722
    example, to tell the user who holds the lock, or to try to detect whether
 
723
    the lock holder is still alive.
 
724
 
 
725
    Prior to bzr 2.4 a simple dict was used instead of an object.
 
726
    """
 
727
 
 
728
    def __init__(self, info_dict):
 
729
        self.info_dict = info_dict
 
730
 
 
731
    def __repr__(self):
 
732
        """Return a debugging representation of this object."""
 
733
        return "%s(%r)" % (self.__class__.__name__, self.info_dict)
 
734
 
 
735
    def __unicode__(self):
 
736
        """Return a user-oriented description of this object."""
 
737
        d = self.to_readable_dict()
 
738
        return ( gettext(
 
739
            u'held by %(user)s on %(hostname)s (process #%(pid)s), '
 
740
            u'acquired %(time_ago)s') % d)
 
741
 
 
742
    def to_readable_dict(self):
 
743
        """Turn the holder info into a dict of human-readable attributes.
 
744
 
 
745
        For example, the start time is presented relative to the current time,
 
746
        rather than as seconds since the epoch.
 
747
 
 
748
        Returns a list of [user, hostname, pid, time_ago] all as readable
 
749
        strings.
 
750
        """
 
751
        start_time = self.info_dict.get('start_time')
 
752
        if start_time is None:
 
753
            time_ago = '(unknown)'
 
754
        else:
 
755
            time_ago = format_delta(
 
756
                time.time() - int(self.info_dict['start_time']))
 
757
        user = self.info_dict.get('user', '<unknown>')
 
758
        hostname = self.info_dict.get('hostname', '<unknown>')
 
759
        pid = self.info_dict.get('pid', '<unknown>')
 
760
        return dict(
 
761
            user=user,
 
762
            hostname=hostname,
 
763
            pid=pid,
 
764
            time_ago=time_ago)
 
765
 
 
766
    def get(self, field_name):
 
767
        """Return the contents of a field from the lock info, or None."""
 
768
        return self.info_dict.get(field_name)
 
769
 
 
770
    @classmethod
 
771
    def for_this_process(cls, extra_holder_info):
 
772
        """Return a new LockHeldInfo for a lock taken by this process.
 
773
        """
 
774
        info = dict(
 
775
            hostname=get_host_name(),
 
776
            pid=str(os.getpid()),
 
777
            nonce=rand_chars(20),
 
778
            start_time=str(int(time.time())),
 
779
            user=get_username_for_lock_info(),
 
780
            )
 
781
        if extra_holder_info is not None:
 
782
            info.update(extra_holder_info)
 
783
        return cls(info)
 
784
 
 
785
    def to_bytes(self):
 
786
        s = rio.Stanza(**self.info_dict)
 
787
        return s.to_string()
 
788
 
 
789
    @classmethod
 
790
    def from_info_file_bytes(cls, info_file_bytes):
 
791
        """Construct from the contents of the held file."""
 
792
        lines = osutils.split_lines(info_file_bytes)
 
793
        try:
 
794
            stanza = rio.read_stanza(lines)
 
795
        except ValueError, e:
 
796
            mutter('Corrupt lock info file: %r', lines)
 
797
            raise LockCorrupt("could not parse lock info file: " + str(e),
 
798
                lines)
 
799
        if stanza is None:
 
800
            # see bug 185013; we fairly often end up with the info file being
 
801
            # empty after an interruption; we could log a message here but
 
802
            # there may not be much we can say
 
803
            return cls({})
 
804
        else:
 
805
            return cls(stanza.as_dict())
 
806
 
 
807
    def __cmp__(self, other):
 
808
        """Value comparison of lock holders."""
 
809
        return (
 
810
            cmp(type(self), type(other))
 
811
            or cmp(self.info_dict, other.info_dict))
 
812
 
 
813
    def is_locked_by_this_process(self):
 
814
        """True if this process seems to be the current lock holder."""
 
815
        return (
 
816
            self.get('hostname') == get_host_name()
 
817
            and self.get('pid') == str(os.getpid())
 
818
            and self.get('user') == get_username_for_lock_info())
 
819
 
 
820
    def is_lock_holder_known_dead(self):
 
821
        """True if the lock holder process is known to be dead.
 
822
 
 
823
        False if it's either known to be still alive, or if we just can't tell.
 
824
 
 
825
        We can be fairly sure the lock holder is dead if it declared the same
 
826
        hostname and there is no process with the given pid alive.  If people
 
827
        have multiple machines with the same hostname this may cause trouble.
 
828
 
 
829
        This doesn't check whether the lock holder is in fact the same process
 
830
        calling this method.  (In that case it will return true.)
 
831
        """
 
832
        if self.get('hostname') != get_host_name():
 
833
            return False
 
834
        if self.get('hostname') == 'localhost':
 
835
            # Too ambiguous.
 
836
            return False
 
837
        if self.get('user') != get_username_for_lock_info():
 
838
            # Could well be another local process by a different user, but
 
839
            # just to be safe we won't conclude about this either.
 
840
            return False
 
841
        pid_str = self.info_dict.get('pid', None)
 
842
        if not pid_str:
 
843
            mutter("no pid recorded in %r" % (self, ))
 
844
            return False
 
845
        try:
 
846
            pid = int(pid_str)
 
847
        except ValueError:
 
848
            mutter("can't parse pid %r from %r"
 
849
                % (pid_str, self))
 
850
            return False
 
851
        return osutils.is_local_pid_dead(pid)
 
852
 
 
853
 
 
854
def get_username_for_lock_info():
 
855
    """Get a username suitable for putting into a lock.
 
856
 
 
857
    It's ok if what's written here is not a proper email address as long
 
858
    as it gives some clue who the user is.
 
859
    """
 
860
    try:
 
861
        return config.GlobalConfig().username()
 
862
    except errors.NoWhoami:
 
863
        return osutils.getuser_unicode()