/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-02-21 06:02:01 UTC
  • mto: This revision was merged to the branch mainline in revision 1569.
  • Revision ID: mbp@sourcefrog.net-20060221060201-5f260bfe331bdc42
New Transport.rename that mustn't overwrite
Change LockDir.is_held to be a property

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
"""lock file protecting a resource
 
18
 
 
19
bzr objects are locked by the existence of a file with a particular name
 
20
within the control directory.  We use this rather than OS internal locks
 
21
(such as flock etc) because they can be seen across all transports,
 
22
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
 
 
81
 
 
82
In the future we may add a "freshen" method which can be called
 
83
by a lock holder to check that their lock has not been broken, and to 
 
84
update the timestamp within it.
 
85
 
 
86
"""
 
87
 
 
88
import os
 
89
import time
 
90
from StringIO import StringIO
 
91
 
 
92
import bzrlib.config
 
93
from bzrlib.errors import (
 
94
        DirectoryNotEmpty,
 
95
        FileExists,
 
96
        LockContention,
 
97
        LockError,
 
98
        LockNotHeld,
 
99
        NoSuchFile,
 
100
        UnlockableTransport,
 
101
        )
 
102
from bzrlib.transport import Transport
 
103
from bzrlib.osutils import rand_chars
 
104
from bzrlib.rio import RioWriter, read_stanza, Stanza
 
105
 
 
106
# XXX: At the moment there is no consideration of thread safety on LockDir
 
107
# objects.  This should perhaps be updated - e.g. if two threads try to take a
 
108
# lock at the same time they should *both* get it.  But then that's unlikely
 
109
# to be a good idea.
 
110
 
 
111
# TODO: After renaming the directory, check the contents are what we
 
112
# expected.  It's possible that the rename failed but the transport lost
 
113
# the failure indication.
 
114
 
 
115
# TODO: Transport could offer a simpler put() method that avoids the
 
116
# rename-into-place for cases like creating the lock template, where there is
 
117
# no chance that the file already exists.
 
118
 
 
119
# TODO: Perhaps store some kind of note like the bzr command line in the lock
 
120
# info?
 
121
 
 
122
# TODO: Some kind of callback run while polling a lock to show progress
 
123
# indicators.
 
124
 
 
125
_DEFAULT_TIMEOUT = 20
 
126
 
 
127
class LockDir(object):
 
128
    """Write-lock guarding access to data.
 
129
    """
 
130
 
 
131
    INFO_NAME = '/info'
 
132
 
 
133
    def __init__(self, transport, path):
 
134
        """Create a new LockDir object.
 
135
 
 
136
        The LockDir is initially unlocked - this just creates the object.
 
137
 
 
138
        :param transport: Transport which will contain the lock
 
139
 
 
140
        :param path: Path to the lock within the base directory of the 
 
141
            transport.
 
142
        """
 
143
        assert isinstance(transport, Transport), \
 
144
            ("not a transport: %r" % transport)
 
145
        self.transport = transport
 
146
        self.path = path
 
147
        self._lock_held = False
 
148
        self._info_path = path + self.INFO_NAME
 
149
        self.nonce = rand_chars(20)
 
150
 
 
151
    def __repr__(self):
 
152
        return '%s(%s%s)' % (self.__class__.__name__,
 
153
                             self.transport.base,
 
154
                             self.path)
 
155
 
 
156
    is_held = property(lambda self: self._lock_held)
 
157
 
 
158
    def attempt_lock(self):
 
159
        """Take the lock; fail if it's already held
 
160
        
 
161
        If you wish to block until the lock can be obtained, call wait_lock()
 
162
        instead.
 
163
        """
 
164
        if self.transport.is_readonly():
 
165
            raise UnlockableTransport(self.transport)
 
166
        try:
 
167
            tmpname = '%s.pending.%s.tmp' % (self.path, rand_chars(20))
 
168
            self.transport.mkdir(tmpname)
 
169
            sio = StringIO()
 
170
            self._prepare_info(sio)
 
171
            sio.seek(0)
 
172
            self.transport.put(tmpname + self.INFO_NAME, sio)
 
173
            # FIXME: this turns into os.rename on posix, but into a fancy rename 
 
174
            # on Windows that may overwrite existing directory trees.  
 
175
            # NB: posix rename will overwrite empty directories, but not 
 
176
            # non-empty directories.
 
177
            self.transport.move(tmpname, self.path)
 
178
            self._lock_held = True
 
179
            return
 
180
        except (DirectoryNotEmpty, FileExists), e:
 
181
            pass
 
182
        # fall through to here on contention
 
183
        raise LockContention(self)
 
184
 
 
185
    def unlock(self):
 
186
        if not self._lock_held:
 
187
            raise LockNotHeld(self)
 
188
        # rename before deleting, because we can't atomically remove the whole
 
189
        # tree
 
190
        tmpname = '%s.releasing.%s.tmp' % (self.path, rand_chars(20))
 
191
        self.transport.move(self.path, tmpname)
 
192
        self._lock_held = False
 
193
        self.transport.delete(tmpname + self.INFO_NAME)
 
194
        self.transport.rmdir(tmpname)
 
195
 
 
196
    def peek(self):
 
197
        """Check if the lock is held by anyone.
 
198
        
 
199
        If it is held, this returns the lock info structure as a rio Stanza,
 
200
        which contains some information about the current lock holder.
 
201
        Otherwise returns None.
 
202
        """
 
203
        try:
 
204
            info = self._parse_info(self.transport.get(self._info_path))
 
205
            assert isinstance(info, Stanza), \
 
206
                    "bad parse result %r" % info
 
207
            return info.as_dict()
 
208
        except NoSuchFile, e:
 
209
            return None
 
210
 
 
211
    def _prepare_info(self, outf):
 
212
        """Write information about a pending lock to a temporary file.
 
213
        """
 
214
        import socket
 
215
        # XXX: is creating this here inefficient?
 
216
        config = bzrlib.config.GlobalConfig()
 
217
        s = Stanza(hostname=socket.gethostname(),
 
218
                   pid=str(os.getpid()),
 
219
                   start_time=str(int(time.time())),
 
220
                   nonce=self.nonce,
 
221
                   user=config.user_email(),
 
222
                   )
 
223
        RioWriter(outf).write_stanza(s)
 
224
 
 
225
    def _parse_info(self, info_file):
 
226
        return read_stanza(info_file.readlines())
 
227
 
 
228
    def wait_lock(self, timeout=20, poll=0.5):
 
229
        """Wait a certain period for a lock.
 
230
 
 
231
        If the lock can be acquired within the bounded time, it
 
232
        is taken and this returns.  Otherwise, LockContention
 
233
        is raised.  Either way, this function should return within
 
234
        approximately `timeout` seconds.  (It may be a bit more if
 
235
        a transport operation takes a long time to complete.)
 
236
        """
 
237
        # XXX: the transport interface doesn't let us guard 
 
238
        # against operations there taking a long time.
 
239
        deadline = time.time() + timeout
 
240
        while True:
 
241
            try:
 
242
                self.attempt_lock()
 
243
                return
 
244
            except LockContention:
 
245
                pass
 
246
            if time.time() + poll < deadline:
 
247
                time.sleep(poll)
 
248
            else:
 
249
                raise LockContention(self)
 
250
 
 
251
    def wait(self, timeout=20, poll=0.5):
 
252
        """Wait a certain period for a lock to be released.
 
253
        """
 
254
        # XXX: the transport interface doesn't let us guard 
 
255
        # against operations there taking a long time.
 
256
        deadline = time.time() + timeout
 
257
        while True:
 
258
            if self.peek():
 
259
                return
 
260
            if time.time() + poll < deadline:
 
261
                time.sleep(poll)
 
262
            else:
 
263
                raise LockContention(self)