/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/lockdir.py

  • Committer: Martin Pool
  • Date: 2006-03-03 07:31:24 UTC
  • mto: This revision was merged to the branch mainline in revision 1593.
  • Revision ID: mbp@sourcefrog.net-20060303073124-c0741f11f36d7236
doc

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/lockdir.py
 
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.wait_lock()
 
91
>>> # do something here
 
92
>>> l.unlock()
 
93
 
 
94
"""
 
95
 
 
96
import os
 
97
import time
 
98
from warnings import warn
 
99
from StringIO import StringIO
 
100
 
 
101
import bzrlib.config
 
102
from bzrlib.errors import (
 
103
        DirectoryNotEmpty,
 
104
        FileExists,
 
105
        LockBreakMismatch,
 
106
        LockBroken,
 
107
        LockContention,
 
108
        LockError,
 
109
        LockNotHeld,
 
110
        NoSuchFile,
 
111
        UnlockableTransport,
 
112
        )
 
113
from bzrlib.transport import Transport
 
114
from bzrlib.osutils import rand_chars
 
115
from bzrlib.rio import RioWriter, read_stanza, Stanza
 
116
 
 
117
# XXX: At the moment there is no consideration of thread safety on LockDir
 
118
# objects.  This should perhaps be updated - e.g. if two threads try to take a
 
119
# lock at the same time they should *both* get it.  But then that's unlikely
 
120
# to be a good idea.
 
121
 
 
122
# TODO: Transport could offer a simpler put() method that avoids the
 
123
# rename-into-place for cases like creating the lock template, where there is
 
124
# no chance that the file already exists.
 
125
 
 
126
# TODO: Perhaps store some kind of note like the bzr command line in the lock
 
127
# info?
 
128
 
 
129
# TODO: Some kind of callback run while polling a lock to show progress
 
130
# indicators.
 
131
 
 
132
_DEFAULT_TIMEOUT_SECONDS = 300
 
133
_DEFAULT_POLL_SECONDS = 0.5
 
134
 
 
135
class LockDir(object):
 
136
    """Write-lock guarding access to data."""
 
137
 
 
138
    __INFO_NAME = '/info'
 
139
 
 
140
    def __init__(self, transport, path):
 
141
        """Create a new LockDir object.
 
142
 
 
143
        The LockDir is initially unlocked - this just creates the object.
 
144
 
 
145
        :param transport: Transport which will contain the lock
 
146
 
 
147
        :param path: Path to the lock within the base directory of the 
 
148
            transport.
 
149
        """
 
150
        assert isinstance(transport, Transport), \
 
151
            ("not a transport: %r" % transport)
 
152
        self.transport = transport
 
153
        self.path = path
 
154
        self._lock_held = False
 
155
        self._info_path = path + self.__INFO_NAME
 
156
        self.nonce = rand_chars(20)
 
157
 
 
158
    def __repr__(self):
 
159
        return '%s(%s%s)' % (self.__class__.__name__,
 
160
                             self.transport.base,
 
161
                             self.path)
 
162
 
 
163
    is_held = property(lambda self: self._lock_held)
 
164
 
 
165
    def attempt_lock(self):
 
166
        """Take the lock; fail if it's already held.
 
167
        
 
168
        If you wish to block until the lock can be obtained, call wait_lock()
 
169
        instead.
 
170
        """
 
171
        if self.transport.is_readonly():
 
172
            raise UnlockableTransport(self.transport)
 
173
        try:
 
174
            tmpname = '%s.pending.%s.tmp' % (self.path, rand_chars(20))
 
175
            self.transport.mkdir(tmpname)
 
176
            sio = StringIO()
 
177
            self._prepare_info(sio)
 
178
            sio.seek(0)
 
179
            self.transport.put(tmpname + self.__INFO_NAME, sio)
 
180
            # FIXME: this turns into os.rename on posix, but into a fancy rename 
 
181
            # on Windows that may overwrite existing directory trees.  
 
182
            # NB: posix rename will overwrite empty directories, but not 
 
183
            # non-empty directories.
 
184
            self.transport.move(tmpname, self.path)
 
185
            self._lock_held = True
 
186
            self.confirm()
 
187
            return
 
188
        except (DirectoryNotEmpty, FileExists), e:
 
189
            pass
 
190
        # fall through to here on contention
 
191
        raise LockContention(self)
 
192
 
 
193
    def unlock(self):
 
194
        """Release a held lock
 
195
        """
 
196
        if not self._lock_held:
 
197
            raise LockNotHeld(self)
 
198
        # rename before deleting, because we can't atomically remove the whole
 
199
        # tree
 
200
        tmpname = '%s.releasing.%s.tmp' % (self.path, rand_chars(20))
 
201
        self.transport.rename(self.path, tmpname)
 
202
        self._lock_held = False
 
203
        self.transport.delete(tmpname + self.__INFO_NAME)
 
204
        self.transport.rmdir(tmpname)
 
205
 
 
206
    def force_break(self, dead_holder_info):
 
207
        """Release a lock held by another process.
 
208
 
 
209
        WARNING: This should only be used when the other process is dead; if
 
210
        it still thinks it has the lock there will be two concurrent writers.
 
211
        In general the user's approval should be sought for lock breaks.
 
212
 
 
213
        dead_holder_info must be the result of a previous LockDir.peek() call;
 
214
        this is used to check that it's still held by the same process that
 
215
        the user decided was dead.  If this is not the current holder,
 
216
        LockBreakMismatch is raised.
 
217
 
 
218
        After the lock is broken it will not be held by any process.
 
219
        It is possible that another process may sneak in and take the 
 
220
        lock before the breaking process acquires it.
 
221
        """
 
222
        if not isinstance(dead_holder_info, dict):
 
223
            raise ValueError("dead_holder_info: %r" % dead_holder_info)
 
224
        if self._lock_held:
 
225
            raise AssertionError("can't break own lock: %r" % self)
 
226
        current_info = self.peek()
 
227
        if current_info is None:
 
228
            # must have been recently released
 
229
            return
 
230
        if current_info != dead_holder_info:
 
231
            raise LockBreakMismatch(self, current_info, dead_holder_info)
 
232
        tmpname = '%s.broken.%s.tmp' % (self.path, rand_chars(20))
 
233
        self.transport.rename(self.path, tmpname)
 
234
        # check that we actually broke the right lock, not someone else;
 
235
        # there's a small race window between checking it and doing the 
 
236
        # rename.
 
237
        broken_info_path = tmpname + self.__INFO_NAME
 
238
        broken_info = self._read_info_file(broken_info_path)
 
239
        if broken_info != dead_holder_info:
 
240
            raise LockBreakMismatch(self, broken_info, dead_holder_info)
 
241
        self.transport.delete(broken_info_path)
 
242
        self.transport.rmdir(tmpname)
 
243
 
 
244
    def confirm(self):
 
245
        """Make sure that the lock is still held by this locker.
 
246
 
 
247
        This should only fail if the lock was broken by user intervention,
 
248
        or if the lock has been affected by a bug.
 
249
 
 
250
        If the lock is not thought to be held, raises LockNotHeld.  If
 
251
        the lock is thought to be held but has been broken, raises 
 
252
        LockBroken.
 
253
        """
 
254
        if not self._lock_held:
 
255
            raise LockNotHeld(self)
 
256
        info = self.peek()
 
257
        if info is None:
 
258
            # no lock there anymore!
 
259
            raise LockBroken(self)
 
260
        if info.get('nonce') != self.nonce:
 
261
            # there is a lock, but not ours
 
262
            raise LockBroken(self)
 
263
        
 
264
    def _read_info_file(self, path):
 
265
        return self._parse_info(self.transport.get(path))
 
266
 
 
267
    def peek(self):
 
268
        """Check if the lock is held by anyone.
 
269
        
 
270
        If it is held, this returns the lock info structure as a rio Stanza,
 
271
        which contains some information about the current lock holder.
 
272
        Otherwise returns None.
 
273
        """
 
274
        try:
 
275
            info = self._read_info_file(self._info_path)
 
276
            assert isinstance(info, dict), \
 
277
                    "bad parse result %r" % info
 
278
            return info
 
279
        except NoSuchFile, e:
 
280
            return None
 
281
 
 
282
    def _prepare_info(self, outf):
 
283
        """Write information about a pending lock to a temporary file.
 
284
        """
 
285
        import socket
 
286
        # XXX: is creating this here inefficient?
 
287
        config = bzrlib.config.GlobalConfig()
 
288
        s = Stanza(hostname=socket.gethostname(),
 
289
                   pid=str(os.getpid()),
 
290
                   start_time=str(int(time.time())),
 
291
                   nonce=self.nonce,
 
292
                   user=config.user_email(),
 
293
                   )
 
294
        RioWriter(outf).write_stanza(s)
 
295
 
 
296
    def _parse_info(self, info_file):
 
297
        return read_stanza(info_file.readlines()).as_dict()
 
298
 
 
299
    def wait_lock(self, timeout=_DEFAULT_TIMEOUT_SECONDS,
 
300
                  poll=_DEFAULT_POLL_SECONDS):
 
301
        """Wait a certain period for a lock.
 
302
 
 
303
        If the lock can be acquired within the bounded time, it
 
304
        is taken and this returns.  Otherwise, LockContention
 
305
        is raised.  Either way, this function should return within
 
306
        approximately `timeout` seconds.  (It may be a bit more if
 
307
        a transport operation takes a long time to complete.)
 
308
        """
 
309
        # XXX: the transport interface doesn't let us guard 
 
310
        # against operations there taking a long time.
 
311
        deadline = time.time() + timeout
 
312
        while True:
 
313
            try:
 
314
                self.attempt_lock()
 
315
                return
 
316
            except LockContention:
 
317
                pass
 
318
            if time.time() + poll < deadline:
 
319
                time.sleep(poll)
 
320
            else:
 
321
                raise LockContention(self)
 
322
 
 
323
    def lock_write(self):
 
324
        """Wait for and acquire the lock."""
 
325
        self.attempt_lock()
 
326
 
 
327
    def lock_read(self):
 
328
        """Compatability-mode shared lock.
 
329
 
 
330
        LockDir doesn't support shared read-only locks, so this 
 
331
        lock is always exclusive.
 
332
        """
 
333
        # At the moment Branches are commonly locked for read, but 
 
334
        # we can't rely on that remotely.  Once this is cleaned up,
 
335
        # reenable this warning to prevent it coming back in 
 
336
        # -- mbp 20060303
 
337
        ## warn("LockDir.lock_read falls back to write lock")
 
338
        self.lock_write()
 
339
 
 
340
    def wait(self, timeout=20, poll=0.5):
 
341
        """Wait a certain period for a lock to be released."""
 
342
        # XXX: the transport interface doesn't let us guard 
 
343
        # against operations there taking a long time.
 
344
        deadline = time.time() + timeout
 
345
        while True:
 
346
            if self.peek():
 
347
                return
 
348
            if time.time() + poll < deadline:
 
349
                time.sleep(poll)
 
350
            else:
 
351
                raise LockContention(self)
 
352