← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/lockdir.py

  • Committer: John Arbash Meinel
  • Date: 2007-04-12 20:27:42 UTC
  • mto: (2399.1.15 doc-cleanup)
  • mto: This revision was merged to the branch mainline in revision 2431.
  • Revision ID: john@arbash-meinel.com-20070412202742-4cr2qmchdfe9mg7n
Cherrypick just the epydoc builder changes.
This is just the piece of change that makes 'make api-docs' work,
without any actual documentation changes.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/lockdir.py
1
 
# Copyright (C) 2006-2011 Canonical Ltd
 
1
# Copyright (C) 2006 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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
 
>>> token = l.wait_lock()
 
91
>>> 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.
99
95
"""
100
96
 
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
 
 
112
97
import os
113
98
import time
 
99
from cStringIO import StringIO
114
100
 
115
101
from bzrlib import (
116
 
    config,
117
 
    debug,
118
102
    errors,
119
 
    lock,
120
 
    osutils,
121
 
    ui,
122
 
    urlutils,
123
103
    )
124
 
from bzrlib.decorators import only_raises
 
104
import bzrlib.config
125
105
from bzrlib.errors import (
126
106
        DirectoryNotEmpty,
127
107
        FileExists,
128
108
        LockBreakMismatch,
129
109
        LockBroken,
130
110
        LockContention,
131
 
        LockCorrupt,
132
 
        LockFailed,
133
111
        LockNotHeld,
134
112
        NoSuchFile,
135
113
        PathError,
136
114
        ResourceBusy,
137
 
        TransportError,
 
115
        UnlockableTransport,
138
116
        )
139
117
from bzrlib.trace import mutter, note
140
 
from bzrlib.osutils import format_delta, rand_chars, get_host_name
141
 
from bzrlib.i18n import gettext
 
118
from bzrlib.transport import Transport
 
119
from bzrlib.osutils import rand_chars, format_delta
 
120
from bzrlib.rio import read_stanza, Stanza
 
121
import bzrlib.ui
142
122
 
143
 
from bzrlib.lazy_import import lazy_import
144
 
lazy_import(globals(), """
145
 
from bzrlib import rio
146
 
""")
147
123
 
148
124
# XXX: At the moment there is no consideration of thread safety on LockDir
149
125
# objects.  This should perhaps be updated - e.g. if two threads try to take a
160
136
# files/dirs created.
161
137
 
162
138
 
163
 
_DEFAULT_TIMEOUT_SECONDS = 30
 
139
_DEFAULT_TIMEOUT_SECONDS = 300
164
140
_DEFAULT_POLL_SECONDS = 1.0
165
141
 
166
142
 
167
 
class LockDir(lock.Lock):
168
 
    """Write-lock guarding access to data.
169
 
    """
 
143
class LockDir(object):
 
144
    """Write-lock guarding access to data."""
170
145
 
171
146
    __INFO_NAME = '/info'
172
147
 
173
 
    def __init__(self, transport, path, file_modebits=0644, dir_modebits=0755,
174
 
        extra_holder_info=None):
 
148
    def __init__(self, transport, path, file_modebits=0644, dir_modebits=0755):
175
149
        """Create a new LockDir object.
176
150
 
177
151
        The LockDir is initially unlocked - this just creates the object.
178
152
 
179
153
        :param transport: Transport which will contain the lock
180
154
 
181
 
        :param path: Path to the lock within the base directory of the
 
155
        :param path: Path to the lock within the base directory of the 
182
156
            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.
187
157
        """
 
158
        assert isinstance(transport, Transport), \
 
159
            ("not a transport: %r" % transport)
188
160
        self.transport = transport
189
161
        self.path = path
190
162
        self._lock_held = False
191
 
        self._locked_via_token = False
192
163
        self._fake_read_lock = False
193
164
        self._held_dir = path + '/held'
194
165
        self._held_info_path = self._held_dir + self.__INFO_NAME
195
166
        self._file_modebits = file_modebits
196
167
        self._dir_modebits = dir_modebits
 
168
        self.nonce = rand_chars(20)
 
169
 
197
170
        self._report_function = note
198
 
        self.extra_holder_info = extra_holder_info
199
 
        self._warned_about_lock_holder = None
200
171
 
201
172
    def __repr__(self):
202
173
        return '%s(%s%s)' % (self.__class__.__name__,
208
179
    def create(self, mode=None):
209
180
        """Create the on-disk lock.
210
181
 
211
 
        This is typically only called when the object/directory containing the
 
182
        This is typically only called when the object/directory containing the 
212
183
        directory is first created.  The lock is not held when it's created.
213
184
        """
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.
 
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.
234
194
        """
235
 
        self._trace("lock_write...")
236
 
        start_time = time.time()
 
195
        if self._fake_read_lock:
 
196
            raise LockContention(self)
 
197
        if self.transport.is_readonly():
 
198
            raise UnlockableTransport(self.transport)
237
199
        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:
 
200
            tmpname = '%s/pending.%s.tmp' % (self.path, rand_chars(20))
243
201
            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")
 
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
 
 
220
            self.transport.rename(tmpname, self._held_dir)
 
221
            self._lock_held = True
 
222
            self.confirm()
 
223
        except errors.PermissionDenied:
 
224
            raise
 
225
        except (PathError, DirectoryNotEmpty, FileExists, ResourceBusy), e:
 
226
            mutter("contention on %r: %s", self, e)
279
227
            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)
 
228
 
346
229
    def unlock(self):
347
230
        """Release a held lock
348
231
        """
350
233
            self._fake_read_lock = False
351
234
            return
352
235
        if not self._lock_held:
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)
 
236
            raise LockNotHeld(self)
 
237
        # rename before deleting, because we can't atomically remove the whole
 
238
        # tree
 
239
        tmpname = '%s/releasing.%s.tmp' % (self.path, rand_chars(20))
 
240
        # gotta own it to unlock
 
241
        self.confirm()
 
242
        self.transport.rename(self._held_dir, tmpname)
 
243
        self._lock_held = False
 
244
        self.transport.delete(tmpname + self.__INFO_NAME)
 
245
        self.transport.rmdir(tmpname)
388
246
 
389
247
    def break_lock(self):
390
248
        """Break a lock not held by this instance of LockDir.
391
249
 
392
 
        This is a UI centric function: it uses the ui.ui_factory to
 
250
        This is a UI centric function: it uses the bzrlib.ui.ui_factory to
393
251
        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.
 
252
        it possibly being still active.
398
253
        """
399
254
        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
 
255
        holder_info = self.peek()
407
256
        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)
415
 
 
 
257
            lock_info = '\n'.join(self._format_lock_info(holder_info))
 
258
            if bzrlib.ui.ui_factory.get_boolean("Break %s" % lock_info):
 
259
                self.force_break(holder_info)
 
260
        
416
261
    def force_break(self, dead_holder_info):
417
262
        """Release a lock held by another process.
418
263
 
420
265
        it still thinks it has the lock there will be two concurrent writers.
421
266
        In general the user's approval should be sought for lock breaks.
422
267
 
 
268
        dead_holder_info must be the result of a previous LockDir.peek() call;
 
269
        this is used to check that it's still held by the same process that
 
270
        the user decided was dead.  If this is not the current holder,
 
271
        LockBreakMismatch is raised.
 
272
 
423
273
        After the lock is broken it will not be held by any process.
424
 
        It is possible that another process may sneak in and take the
 
274
        It is possible that another process may sneak in and take the 
425
275
        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.
434
276
        """
435
 
        if not isinstance(dead_holder_info, LockHeldInfo):
 
277
        if not isinstance(dead_holder_info, dict):
436
278
            raise ValueError("dead_holder_info: %r" % dead_holder_info)
437
279
        self._check_not_locked()
438
280
        current_info = self.peek()
444
286
        tmpname = '%s/broken.%s.tmp' % (self.path, rand_chars(20))
445
287
        self.transport.rename(self._held_dir, tmpname)
446
288
        # check that we actually broke the right lock, not someone else;
447
 
        # there's a small race window between checking it and doing the
 
289
        # there's a small race window between checking it and doing the 
448
290
        # rename.
449
291
        broken_info_path = tmpname + self.__INFO_NAME
450
292
        broken_info = self._read_info_file(broken_info_path)
452
294
            raise LockBreakMismatch(self, broken_info, dead_holder_info)
453
295
        self.transport.delete(broken_info_path)
454
296
        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
297
 
490
298
    def _check_not_locked(self):
491
299
        """If the lock is held by this instance, raise an error."""
499
307
        or if the lock has been affected by a bug.
500
308
 
501
309
        If the lock is not thought to be held, raises LockNotHeld.  If
502
 
        the lock is thought to be held but has been broken, raises
 
310
        the lock is thought to be held but has been broken, raises 
503
311
        LockBroken.
504
312
        """
505
313
        if not self._lock_held:
511
319
        if info.get('nonce') != self.nonce:
512
320
            # there is a lock, but not ours
513
321
            raise LockBroken(self)
514
 
 
 
322
        
515
323
    def _read_info_file(self, path):
516
324
        """Read one given info file.
517
325
 
518
326
        peek() reads the info file of the lock holder, if any.
519
327
        """
520
 
        return LockHeldInfo.from_info_file_bytes(
521
 
            self.transport.get_bytes(path))
 
328
        return self._parse_info(self.transport.get(path))
522
329
 
523
330
    def peek(self):
524
331
        """Check if the lock is held by anyone.
525
 
 
526
 
        If it is held, this returns the lock info structure as a dict
 
332
        
 
333
        If it is held, this returns the lock info structure as a rio Stanza,
527
334
        which contains some information about the current lock holder.
528
335
        Otherwise returns None.
529
336
        """
530
337
        try:
531
338
            info = self._read_info_file(self._held_info_path)
532
 
            self._trace("peek -> held")
 
339
            assert isinstance(info, dict), \
 
340
                    "bad parse result %r" % info
533
341
            return info
534
342
        except NoSuchFile, e:
535
 
            self._trace("peek -> not held")
 
343
            return None
536
344
 
537
345
    def _prepare_info(self):
538
346
        """Write information about a pending lock to a temporary file.
539
347
        """
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):
 
348
        import socket
 
349
        # XXX: is creating this here inefficient?
 
350
        config = bzrlib.config.GlobalConfig()
 
351
        try:
 
352
            user = config.user_email()
 
353
        except errors.NoEmailInUsername:
 
354
            user = config.username()
 
355
        s = Stanza(hostname=socket.gethostname(),
 
356
                   pid=str(os.getpid()),
 
357
                   start_time=str(int(time.time())),
 
358
                   nonce=self.nonce,
 
359
                   user=user,
 
360
                   )
 
361
        return s.to_string()
 
362
 
 
363
    def _parse_info(self, info_file):
 
364
        return read_stanza(info_file.readlines()).as_dict()
 
365
 
 
366
    def wait_lock(self, timeout=None, poll=None):
571
367
        """Wait a certain period for a lock.
572
368
 
573
369
        If the lock can be acquired within the bounded time, it
575
371
        is raised.  Either way, this function should return within
576
372
        approximately `timeout` seconds.  (It may be a bit more if
577
373
        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.
587
374
        """
588
375
        if timeout is None:
589
376
            timeout = _DEFAULT_TIMEOUT_SECONDS
590
377
        if poll is None:
591
378
            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.
 
379
 
 
380
        # XXX: the transport interface doesn't let us guard 
 
381
        # against operations there taking a long time.
595
382
        deadline = time.time() + timeout
596
383
        deadline_str = None
597
384
        last_info = None
598
 
        attempt_count = 0
599
 
        lock_url = self.lock_url_for_display()
600
385
        while True:
601
 
            attempt_count += 1
602
386
            try:
603
 
                return self.attempt_lock()
 
387
                self.attempt_lock()
 
388
                return
604
389
            except LockContention:
605
 
                # possibly report the blockage, then try again
606
390
                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
391
            new_info = self.peek()
 
392
            mutter('last_info: %s, new info: %s', last_info, new_info)
614
393
            if new_info is not None and new_info != last_info:
615
394
                if last_info is None:
616
 
                    start = gettext('Unable to obtain')
 
395
                    start = 'Unable to obtain'
617
396
                else:
618
 
                    start = gettext('Lock owner changed for')
 
397
                    start = 'Lock owner changed for'
619
398
                last_info = new_info
620
 
                msg = gettext('{0} lock {1} {2}.').format(start, lock_url,
621
 
                                                                    new_info)
 
399
                formatted_info = self._format_lock_info(new_info)
622
400
                if deadline_str is None:
623
401
                    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)
 
402
                                                 time.localtime(deadline))
 
403
                self._report_function('%s %s\n'
 
404
                                      '%s\n' # held by
 
405
                                      '%s\n' # locked ... ago
 
406
                                      'Will continue to try until %s\n',
 
407
                                      start,
 
408
                                      formatted_info[0],
 
409
                                      formatted_info[1],
 
410
                                      formatted_info[2],
 
411
                                      deadline_str)
 
412
 
634
413
            if time.time() + poll < deadline:
635
 
                self._trace("waiting %ss", poll)
636
414
                time.sleep(poll)
637
415
            else:
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()
 
416
                raise LockContention(self)
 
417
 
 
418
    def lock_write(self):
 
419
        """Wait for and acquire the lock."""
 
420
        self.wait_lock()
675
421
 
676
422
    def lock_read(self):
677
423
        """Compatibility-mode shared lock.
678
424
 
679
 
        LockDir doesn't support shared read-only locks, so this
 
425
        LockDir doesn't support shared read-only locks, so this 
680
426
        just pretends that the lock is taken but really does nothing.
681
427
        """
682
 
        # At the moment Branches are commonly locked for read, but
 
428
        # At the moment Branches are commonly locked for read, but 
683
429
        # we can't rely on that remotely.  Once this is cleaned up,
684
 
        # reenable this warning to prevent it coming back in
 
430
        # reenable this warning to prevent it coming back in 
685
431
        # -- mbp 20060303
686
432
        ## warn("LockDir.lock_read falls back to write lock")
687
433
        if self._lock_held or self._fake_read_lock:
688
434
            raise LockContention(self)
689
435
        self._fake_read_lock = True
690
436
 
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()
 
437
    def wait(self, timeout=20, poll=0.5):
 
438
        """Wait a certain period for a lock to be released."""
 
439
        # XXX: the transport interface doesn't let us guard 
 
440
        # against operations there taking a long time.
 
441
        deadline = time.time() + timeout
 
442
        while True:
 
443
            if self.peek():
 
444
                return
 
445
            if time.time() + poll < deadline:
 
446
                time.sleep(poll)
 
447
            else:
 
448
                raise LockContention(self)
 
449
 
 
450
    def _format_lock_info(self, info):
 
451
        """Turn the contents of peek() into something for the user"""
 
452
        lock_url = self.transport.abspath(self.path)
 
453
        delta = time.time() - int(info['start_time'])
 
454
        return [
 
455
            'lock %s' % (lock_url,),
 
456
            'held by %(user)s on host %(hostname)s [process #%(pid)s]' % info,
 
457
            'locked %s' % (format_delta(delta),),
 
458
            ]
 
459