← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/lockdir.py

  • Committer: Patch Queue Manager
  • Date: 2016-04-21 05:06:57 UTC
  • mfrom: (6603.4.1 bzr)
  • Revision ID: pqm@pqm.ubuntu.com-20160421050657-ygnzfybewvudf1j9
(richard-wilbur) Use initial_comment as commit_message for lp_propose.(Shawn
 Wang) (Shawn Wang)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/lockdir.py
1
 
# Copyright (C) 2006 Canonical Ltd
2
 
 
 
1
# Copyright (C) 2006-2011 Canonical Ltd
 
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
5
5
# the Free Software Foundation; either version 2 of the License, or
6
6
# (at your option) any later version.
7
 
 
 
7
#
8
8
# This program is distributed in the hope that it will be useful,
9
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
11
# GNU General Public License for more details.
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 warnings import warn
100
 
from StringIO import StringIO
101
114
 
102
 
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
103
125
from bzrlib.errors import (
104
126
        DirectoryNotEmpty,
105
127
        FileExists,
106
128
        LockBreakMismatch,
107
129
        LockBroken,
108
130
        LockContention,
109
 
        LockError,
 
131
        LockCorrupt,
 
132
        LockFailed,
110
133
        LockNotHeld,
111
134
        NoSuchFile,
 
135
        PathError,
112
136
        ResourceBusy,
113
 
        UnlockableTransport,
 
137
        TransportError,
114
138
        )
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
121
150
# lock at the same time they should *both* get it.  But then that's unlikely
122
151
# to be a good idea.
123
152
 
124
 
# TODO: Transport could offer a simpler put() method that avoids the
125
 
# rename-into-place for cases like creating the lock template, where there is
126
 
# no chance that the file already exists.
127
 
 
128
153
# TODO: Perhaps store some kind of note like the bzr command line in the lock
129
154
# info?
130
155
 
134
159
# TODO: Make sure to pass the right file and directory mode bits to all
135
160
# files/dirs created.
136
161
 
137
 
_DEFAULT_TIMEOUT_SECONDS = 300
138
 
_DEFAULT_POLL_SECONDS = 0.5
139
 
 
140
 
class LockDir(object):
141
 
    """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
    """
142
170
 
143
171
    __INFO_NAME = '/info'
144
172
 
145
 
    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):
146
175
        """Create a new LockDir object.
147
176
 
148
177
        The LockDir is initially unlocked - this just creates the object.
149
178
 
150
179
        :param transport: Transport which will contain the lock
151
180
 
152
 
        :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
153
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.
154
187
        """
155
 
        assert isinstance(transport, Transport), \
156
 
            ("not a transport: %r" % transport)
157
188
        self.transport = transport
158
189
        self.path = path
159
190
        self._lock_held = False
 
191
        self._locked_via_token = False
160
192
        self._fake_read_lock = False
161
193
        self._held_dir = path + '/held'
162
194
        self._held_info_path = self._held_dir + self.__INFO_NAME
163
195
        self._file_modebits = file_modebits
164
196
        self._dir_modebits = dir_modebits
165
 
        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
166
200
 
167
201
    def __repr__(self):
168
202
        return '%s(%s%s)' % (self.__class__.__name__,
174
208
    def create(self, mode=None):
175
209
        """Create the on-disk lock.
176
210
 
177
 
        This is typically only called when the object/directory containing the 
 
211
        This is typically only called when the object/directory containing the
178
212
        directory is first created.  The lock is not held when it's created.
179
213
        """
180
 
        if self.transport.is_readonly():
181
 
            raise UnlockableTransport(self.transport)
182
 
        self.transport.mkdir(self.path, mode=mode)
183
 
 
184
 
    def attempt_lock(self):
185
 
        """Take the lock; fail if it's already held.
186
 
        
187
 
        If you wish to block until the lock can be obtained, call wait_lock()
188
 
        instead.
 
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.
189
234
        """
190
 
        if self._fake_read_lock:
 
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")
191
279
            raise LockContention(self)
192
 
        if self.transport.is_readonly():
193
 
            raise UnlockableTransport(self.transport)
194
 
        try:
195
 
            tmpname = '%s/pending.%s.tmp' % (self.path, rand_chars(20))
196
 
            self.transport.mkdir(tmpname)
197
 
            sio = StringIO()
198
 
            self._prepare_info(sio)
199
 
            sio.seek(0)
200
 
            self.transport.put(tmpname + self.__INFO_NAME, sio)
201
 
            self.transport.rename(tmpname, self._held_dir)
202
 
            self._lock_held = True
203
 
            self.confirm()
204
 
            return
205
 
        except (DirectoryNotEmpty, FileExists, ResourceBusy), e:
206
 
            pass
207
 
        # fall through to here on contention
 
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
208
308
        raise LockContention(self)
209
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)
210
346
    def unlock(self):
211
347
        """Release a held lock
212
348
        """
214
350
            self._fake_read_lock = False
215
351
            return
216
352
        if not self._lock_held:
217
 
            raise LockNotHeld(self)
218
 
        # rename before deleting, because we can't atomically remove the whole
219
 
        # tree
220
 
        tmpname = '%s/releasing.%s.tmp' % (self.path, rand_chars(20))
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)
 
388
 
 
389
    def break_lock(self):
 
390
        """Break a lock not held by this instance of LockDir.
 
391
 
 
392
        This is a UI centric function: it uses the ui.ui_factory to
 
393
        prompt for input if a lock is detected and there is any doubt about
 
394
        it possibly being still active.  force_break is the non-interactive
 
395
        version.
 
396
 
 
397
        :returns: LockResult for the broken lock.
 
398
        """
 
399
        self._check_not_locked()
 
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
 
407
        if holder_info is not None:
 
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)
225
415
 
226
416
    def force_break(self, dead_holder_info):
227
417
        """Release a lock held by another process.
230
420
        it still thinks it has the lock there will be two concurrent writers.
231
421
        In general the user's approval should be sought for lock breaks.
232
422
 
233
 
        dead_holder_info must be the result of a previous LockDir.peek() call;
234
 
        this is used to check that it's still held by the same process that
235
 
        the user decided was dead.  If this is not the current holder,
236
 
        LockBreakMismatch is raised.
237
 
 
238
423
        After the lock is broken it will not be held by any process.
239
 
        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
240
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.
241
434
        """
242
 
        if not isinstance(dead_holder_info, dict):
 
435
        if not isinstance(dead_holder_info, LockHeldInfo):
243
436
            raise ValueError("dead_holder_info: %r" % dead_holder_info)
244
 
        if self._lock_held:
245
 
            raise AssertionError("can't break own lock: %r" % self)
 
437
        self._check_not_locked()
246
438
        current_info = self.peek()
247
439
        if current_info is None:
248
440
            # must have been recently released
252
444
        tmpname = '%s/broken.%s.tmp' % (self.path, rand_chars(20))
253
445
        self.transport.rename(self._held_dir, tmpname)
254
446
        # check that we actually broke the right lock, not someone else;
255
 
        # 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
256
448
        # rename.
257
449
        broken_info_path = tmpname + self.__INFO_NAME
258
450
        broken_info = self._read_info_file(broken_info_path)
260
452
            raise LockBreakMismatch(self, broken_info, dead_holder_info)
261
453
        self.transport.delete(broken_info_path)
262
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)
 
489
 
 
490
    def _check_not_locked(self):
 
491
        """If the lock is held by this instance, raise an error."""
 
492
        if self._lock_held:
 
493
            raise AssertionError("can't break own lock: %r" % self)
263
494
 
264
495
    def confirm(self):
265
496
        """Make sure that the lock is still held by this locker.
268
499
        or if the lock has been affected by a bug.
269
500
 
270
501
        If the lock is not thought to be held, raises LockNotHeld.  If
271
 
        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
272
503
        LockBroken.
273
504
        """
274
505
        if not self._lock_held:
280
511
        if info.get('nonce') != self.nonce:
281
512
            # there is a lock, but not ours
282
513
            raise LockBroken(self)
283
 
        
 
514
 
284
515
    def _read_info_file(self, path):
285
516
        """Read one given info file.
286
517
 
287
518
        peek() reads the info file of the lock holder, if any.
288
519
        """
289
 
        return self._parse_info(self.transport.get(path))
 
520
        return LockHeldInfo.from_info_file_bytes(
 
521
            self.transport.get_bytes(path))
290
522
 
291
523
    def peek(self):
292
524
        """Check if the lock is held by anyone.
293
 
        
294
 
        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
295
527
        which contains some information about the current lock holder.
296
528
        Otherwise returns None.
297
529
        """
298
530
        try:
299
531
            info = self._read_info_file(self._held_info_path)
300
 
            assert isinstance(info, dict), \
301
 
                    "bad parse result %r" % info
 
532
            self._trace("peek -> held")
302
533
            return info
303
534
        except NoSuchFile, e:
304
 
            return None
 
535
            self._trace("peek -> not held")
305
536
 
306
 
    def _prepare_info(self, outf):
 
537
    def _prepare_info(self):
307
538
        """Write information about a pending lock to a temporary file.
308
539
        """
309
 
        import socket
310
 
        # XXX: is creating this here inefficient?
311
 
        config = bzrlib.config.GlobalConfig()
312
 
        s = Stanza(hostname=socket.gethostname(),
313
 
                   pid=str(os.getpid()),
314
 
                   start_time=str(int(time.time())),
315
 
                   nonce=self.nonce,
316
 
                   user=config.user_email(),
317
 
                   )
318
 
        RioWriter(outf).write_stanza(s)
319
 
 
320
 
    def _parse_info(self, info_file):
321
 
        return read_stanza(info_file.readlines()).as_dict()
322
 
 
323
 
    def wait_lock(self, timeout=_DEFAULT_TIMEOUT_SECONDS,
324
 
                  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):
325
571
        """Wait a certain period for a lock.
326
572
 
327
573
        If the lock can be acquired within the bounded time, it
329
575
        is raised.  Either way, this function should return within
330
576
        approximately `timeout` seconds.  (It may be a bit more if
331
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.
332
587
        """
333
 
        # XXX: the transport interface doesn't let us guard 
334
 
        # 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.
335
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()
336
600
        while True:
 
601
            attempt_count += 1
337
602
            try:
338
 
                self.attempt_lock()
339
 
                return
 
603
                return self.attempt_lock()
340
604
            except LockContention:
 
605
                # possibly report the blockage, then try again
341
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)
342
634
            if time.time() + poll < deadline:
 
635
                self._trace("waiting %ss", poll)
343
636
                time.sleep(poll)
344
637
            else:
345
 
                raise LockContention(self)
346
 
 
347
 
    def lock_write(self):
348
 
        """Wait for and acquire the lock."""
349
 
        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()
350
675
 
351
676
    def lock_read(self):
352
 
        """Compatability-mode shared lock.
 
677
        """Compatibility-mode shared lock.
353
678
 
354
 
        LockDir doesn't support shared read-only locks, so this 
 
679
        LockDir doesn't support shared read-only locks, so this
355
680
        just pretends that the lock is taken but really does nothing.
356
681
        """
357
 
        # At the moment Branches are commonly locked for read, but 
 
682
        # At the moment Branches are commonly locked for read, but
358
683
        # we can't rely on that remotely.  Once this is cleaned up,
359
 
        # reenable this warning to prevent it coming back in 
 
684
        # reenable this warning to prevent it coming back in
360
685
        # -- mbp 20060303
361
686
        ## warn("LockDir.lock_read falls back to write lock")
362
687
        if self._lock_held or self._fake_read_lock:
363
688
            raise LockContention(self)
364
689
        self._fake_read_lock = True
365
690
 
366
 
    def wait(self, timeout=20, poll=0.5):
367
 
        """Wait a certain period for a lock to be released."""
368
 
        # XXX: the transport interface doesn't let us guard 
369
 
        # against operations there taking a long time.
370
 
        deadline = time.time() + timeout
371
 
        while True:
372
 
            if self.peek():
373
 
                return
374
 
            if time.time() + poll < deadline:
375
 
                time.sleep(poll)
376
 
            else:
377
 
                raise LockContention(self)
378
 
 
 
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.GlobalStack().get('email')
 
862
    except errors.NoWhoami:
 
863
        return osutils.getuser_unicode()