~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/lockdir.py

- refactor handling of short option names

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2006 Canonical Ltd
2
 
 
3
 
# This program is free software; you can redistribute it and/or modify
4
 
# it under the terms of the GNU General Public License as published by
5
 
# the Free Software Foundation; either version 2 of the License, or
6
 
# (at your option) any later version.
7
 
 
8
 
# This program is distributed in the hope that it will be useful,
9
 
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
 
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
 
# GNU General Public License for more details.
12
 
 
13
 
# You should have received a copy of the GNU General Public License
14
 
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
 
 
17
 
"""On-disk mutex protecting a resource
18
 
 
19
 
bzr on-disk objects are locked by the existence of a directory with a
20
 
particular name within the control directory.  We use this rather than OS
21
 
internal locks (such as flock etc) because they can be seen across all
22
 
transports, including http.
23
 
 
24
 
Objects can be read if there is only physical read access; therefore 
25
 
readers can never be required to create a lock, though they will
26
 
check whether a writer is using the lock.  Writers can't detect
27
 
whether anyone else is reading from the resource as they write.
28
 
This works because of ordering constraints that make sure readers
29
 
see a consistent view of existing data.
30
 
 
31
 
Waiting for a lock must be done by polling; this can be aborted after
32
 
a timeout.
33
 
 
34
 
Locks must always be explicitly released, typically from a try/finally
35
 
block -- they are not released from a finalizer or when Python
36
 
exits.
37
 
 
38
 
Locks may fail to be released if the process is abruptly terminated
39
 
(machine stop, SIGKILL) or if a remote transport becomes permanently
40
 
disconnected.  There is therefore a method to break an existing lock.
41
 
This should rarely be used, and generally only with user approval.
42
 
Locks contain some information on when the lock was taken and by who
43
 
which may guide in deciding whether it can safely be broken.  (This is
44
 
similar to the messages displayed by emacs and vim.) Note that if the
45
 
lock holder is still alive they will get no notification that the lock
46
 
has been broken and will continue their work -- so it is important to be
47
 
sure they are actually dead.
48
 
 
49
 
A lock is represented on disk by a directory of a particular name,
50
 
containing an information file.  Taking a lock is done by renaming a
51
 
temporary directory into place.  We use temporary directories because
52
 
for all known transports and filesystems we believe that exactly one
53
 
attempt to claim the lock will succeed and the others will fail.  (Files
54
 
won't do because some filesystems or transports only have
55
 
rename-and-overwrite, making it hard to tell who won.)
56
 
 
57
 
The desired characteristics are:
58
 
 
59
 
* Locks are not reentrant.  (That is, a client that tries to take a 
60
 
  lock it already holds may deadlock or fail.)
61
 
* Stale locks can be guessed at by a heuristic
62
 
* Lost locks can be broken by any client
63
 
* Failed lock operations leave little or no mess
64
 
* Deadlocks are avoided by having a timeout always in use, clients
65
 
  desiring indefinite waits can retry or set a silly big timeout.
66
 
 
67
 
Storage formats use the locks, and also need to consider concurrency
68
 
issues underneath the lock.  A format may choose not to use a lock
69
 
at all for some operations.
70
 
 
71
 
LockDirs always operate over a Transport.  The transport may be readonly, in
72
 
which case the lock can be queried but not acquired.
73
 
 
74
 
Locks are identified by a path name, relative to a base transport.
75
 
 
76
 
Calling code will typically want to make sure there is exactly one LockDir
77
 
object per actual lock on disk.  This module does nothing to prevent aliasing
78
 
and deadlocks will likely occur if the locks are aliased.
79
 
 
80
 
In the future we may add a "freshen" method which can be called
81
 
by a lock holder to check that their lock has not been broken, and to 
82
 
update the timestamp within it.
83
 
 
84
 
Example usage:
85
 
 
86
 
>>> from bzrlib.transport.memory import MemoryTransport
87
 
>>> # typically will be obtained from a BzrDir, Branch, etc
88
 
>>> t = MemoryTransport()
89
 
>>> l = LockDir(t, 'sample-lock')
90
 
>>> l.create()
91
 
>>> l.wait_lock()
92
 
>>> # do something here
93
 
>>> l.unlock()
94
 
 
95
 
"""
96
 
 
97
 
import os
98
 
import time
99
 
from warnings import warn
100
 
from StringIO import StringIO
101
 
 
102
 
import bzrlib.config
103
 
from bzrlib.errors import (
104
 
        DirectoryNotEmpty,
105
 
        FileExists,
106
 
        LockBreakMismatch,
107
 
        LockBroken,
108
 
        LockContention,
109
 
        LockError,
110
 
        LockNotHeld,
111
 
        NoSuchFile,
112
 
        PathError,
113
 
        ResourceBusy,
114
 
        UnlockableTransport,
115
 
        )
116
 
from bzrlib.trace import mutter
117
 
from bzrlib.transport import Transport
118
 
from bzrlib.osutils import rand_chars
119
 
from bzrlib.rio import RioWriter, read_stanza, Stanza
120
 
 
121
 
# XXX: At the moment there is no consideration of thread safety on LockDir
122
 
# objects.  This should perhaps be updated - e.g. if two threads try to take a
123
 
# lock at the same time they should *both* get it.  But then that's unlikely
124
 
# to be a good idea.
125
 
 
126
 
# TODO: Transport could offer a simpler put() method that avoids the
127
 
# rename-into-place for cases like creating the lock template, where there is
128
 
# no chance that the file already exists.
129
 
 
130
 
# TODO: Perhaps store some kind of note like the bzr command line in the lock
131
 
# info?
132
 
 
133
 
# TODO: Some kind of callback run while polling a lock to show progress
134
 
# indicators.
135
 
 
136
 
# TODO: Make sure to pass the right file and directory mode bits to all
137
 
# files/dirs created.
138
 
 
139
 
_DEFAULT_TIMEOUT_SECONDS = 300
140
 
_DEFAULT_POLL_SECONDS = 0.5
141
 
 
142
 
class LockDir(object):
143
 
    """Write-lock guarding access to data."""
144
 
 
145
 
    __INFO_NAME = '/info'
146
 
 
147
 
    def __init__(self, transport, path, file_modebits=0644, dir_modebits=0755):
148
 
        """Create a new LockDir object.
149
 
 
150
 
        The LockDir is initially unlocked - this just creates the object.
151
 
 
152
 
        :param transport: Transport which will contain the lock
153
 
 
154
 
        :param path: Path to the lock within the base directory of the 
155
 
            transport.
156
 
        """
157
 
        assert isinstance(transport, Transport), \
158
 
            ("not a transport: %r" % transport)
159
 
        self.transport = transport
160
 
        self.path = path
161
 
        self._lock_held = False
162
 
        self._fake_read_lock = False
163
 
        self._held_dir = path + '/held'
164
 
        self._held_info_path = self._held_dir + self.__INFO_NAME
165
 
        self._file_modebits = file_modebits
166
 
        self._dir_modebits = dir_modebits
167
 
        self.nonce = rand_chars(20)
168
 
 
169
 
    def __repr__(self):
170
 
        return '%s(%s%s)' % (self.__class__.__name__,
171
 
                             self.transport.base,
172
 
                             self.path)
173
 
 
174
 
    is_held = property(lambda self: self._lock_held)
175
 
 
176
 
    def create(self, mode=None):
177
 
        """Create the on-disk lock.
178
 
 
179
 
        This is typically only called when the object/directory containing the 
180
 
        directory is first created.  The lock is not held when it's created.
181
 
        """
182
 
        if self.transport.is_readonly():
183
 
            raise UnlockableTransport(self.transport)
184
 
        self.transport.mkdir(self.path, mode=mode)
185
 
 
186
 
    def attempt_lock(self):
187
 
        """Take the lock; fail if it's already held.
188
 
        
189
 
        If you wish to block until the lock can be obtained, call wait_lock()
190
 
        instead.
191
 
        """
192
 
        if self._fake_read_lock:
193
 
            raise LockContention(self)
194
 
        if self.transport.is_readonly():
195
 
            raise UnlockableTransport(self.transport)
196
 
        try:
197
 
            tmpname = '%s/pending.%s.tmp' % (self.path, rand_chars(20))
198
 
            self.transport.mkdir(tmpname)
199
 
            sio = StringIO()
200
 
            self._prepare_info(sio)
201
 
            sio.seek(0)
202
 
            self.transport.put(tmpname + self.__INFO_NAME, sio)
203
 
            self.transport.rename(tmpname, self._held_dir)
204
 
            self._lock_held = True
205
 
            self.confirm()
206
 
        except (PathError, DirectoryNotEmpty, FileExists, ResourceBusy), e:
207
 
            mutter("contention on %r: %s", self, e)
208
 
            raise LockContention(self)
209
 
 
210
 
    def unlock(self):
211
 
        """Release a held lock
212
 
        """
213
 
        if self._fake_read_lock:
214
 
            self._fake_read_lock = False
215
 
            return
216
 
        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)
225
 
 
226
 
    def force_break(self, dead_holder_info):
227
 
        """Release a lock held by another process.
228
 
 
229
 
        WARNING: This should only be used when the other process is dead; if
230
 
        it still thinks it has the lock there will be two concurrent writers.
231
 
        In general the user's approval should be sought for lock breaks.
232
 
 
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
 
        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 
240
 
        lock before the breaking process acquires it.
241
 
        """
242
 
        if not isinstance(dead_holder_info, dict):
243
 
            raise ValueError("dead_holder_info: %r" % dead_holder_info)
244
 
        if self._lock_held:
245
 
            raise AssertionError("can't break own lock: %r" % self)
246
 
        current_info = self.peek()
247
 
        if current_info is None:
248
 
            # must have been recently released
249
 
            return
250
 
        if current_info != dead_holder_info:
251
 
            raise LockBreakMismatch(self, current_info, dead_holder_info)
252
 
        tmpname = '%s/broken.%s.tmp' % (self.path, rand_chars(20))
253
 
        self.transport.rename(self._held_dir, tmpname)
254
 
        # check that we actually broke the right lock, not someone else;
255
 
        # there's a small race window between checking it and doing the 
256
 
        # rename.
257
 
        broken_info_path = tmpname + self.__INFO_NAME
258
 
        broken_info = self._read_info_file(broken_info_path)
259
 
        if broken_info != dead_holder_info:
260
 
            raise LockBreakMismatch(self, broken_info, dead_holder_info)
261
 
        self.transport.delete(broken_info_path)
262
 
        self.transport.rmdir(tmpname)
263
 
 
264
 
    def confirm(self):
265
 
        """Make sure that the lock is still held by this locker.
266
 
 
267
 
        This should only fail if the lock was broken by user intervention,
268
 
        or if the lock has been affected by a bug.
269
 
 
270
 
        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 
272
 
        LockBroken.
273
 
        """
274
 
        if not self._lock_held:
275
 
            raise LockNotHeld(self)
276
 
        info = self.peek()
277
 
        if info is None:
278
 
            # no lock there anymore!
279
 
            raise LockBroken(self)
280
 
        if info.get('nonce') != self.nonce:
281
 
            # there is a lock, but not ours
282
 
            raise LockBroken(self)
283
 
        
284
 
    def _read_info_file(self, path):
285
 
        """Read one given info file.
286
 
 
287
 
        peek() reads the info file of the lock holder, if any.
288
 
        """
289
 
        return self._parse_info(self.transport.get(path))
290
 
 
291
 
    def peek(self):
292
 
        """Check if the lock is held by anyone.
293
 
        
294
 
        If it is held, this returns the lock info structure as a rio Stanza,
295
 
        which contains some information about the current lock holder.
296
 
        Otherwise returns None.
297
 
        """
298
 
        try:
299
 
            info = self._read_info_file(self._held_info_path)
300
 
            assert isinstance(info, dict), \
301
 
                    "bad parse result %r" % info
302
 
            return info
303
 
        except NoSuchFile, e:
304
 
            return None
305
 
 
306
 
    def _prepare_info(self, outf):
307
 
        """Write information about a pending lock to a temporary file.
308
 
        """
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):
325
 
        """Wait a certain period for a lock.
326
 
 
327
 
        If the lock can be acquired within the bounded time, it
328
 
        is taken and this returns.  Otherwise, LockContention
329
 
        is raised.  Either way, this function should return within
330
 
        approximately `timeout` seconds.  (It may be a bit more if
331
 
        a transport operation takes a long time to complete.)
332
 
        """
333
 
        # XXX: the transport interface doesn't let us guard 
334
 
        # against operations there taking a long time.
335
 
        deadline = time.time() + timeout
336
 
        while True:
337
 
            try:
338
 
                self.attempt_lock()
339
 
                return
340
 
            except LockContention:
341
 
                pass
342
 
            if time.time() + poll < deadline:
343
 
                time.sleep(poll)
344
 
            else:
345
 
                raise LockContention(self)
346
 
 
347
 
    def lock_write(self):
348
 
        """Wait for and acquire the lock."""
349
 
        self.attempt_lock()
350
 
 
351
 
    def lock_read(self):
352
 
        """Compatability-mode shared lock.
353
 
 
354
 
        LockDir doesn't support shared read-only locks, so this 
355
 
        just pretends that the lock is taken but really does nothing.
356
 
        """
357
 
        # At the moment Branches are commonly locked for read, but 
358
 
        # we can't rely on that remotely.  Once this is cleaned up,
359
 
        # reenable this warning to prevent it coming back in 
360
 
        # -- mbp 20060303
361
 
        ## warn("LockDir.lock_read falls back to write lock")
362
 
        if self._lock_held or self._fake_read_lock:
363
 
            raise LockContention(self)
364
 
        self._fake_read_lock = True
365
 
 
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