← Back to branch summary

~svn/ubuntu/raring/subversion/ppa

« back to all changes in this revision

Viewing changes to notes/locking/locking-implementation.txt

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-12-05 01:26:14 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20051205012614-qom4xfypgtsqc2xq
Tags: 1.2.3dfsg1-3ubuntu1
Merge with the final Debian release of 1.2.3dfsg1-3, bringing in
fixes to the clean target, better documentation of the libdb4.3
upgrade and build fixes to work with swig1.3_1.3.27.

Show diffs side-by-side

added added

removed removed

Lines of Context:
notes/locking/locking-implementation.txt
 
1
Implementation for "Locking" feature
 
2
 
 
3
This document describes proposed implementation details for a new
 
4
locking system in Subversion.
 
5
 
 
6
I. Introduction
 
7
 
 
8
II. Client Implementation
 
9
 
 
10
   A. Overview
 
11
 
 
12
   B. The "svn:needs-lock" property
 
13
 
 
14
      1. Property as enforcement system
 
15
 
 
16
      2. Property as communication system
 
17
 
 
18
   C. Lock manipulation via client
 
19
 
 
20
      1. Lock Tokens
 
21
 
 
22
          Stored as 'entryprops'.  That is, just like
 
23
          last-changed-rev, last-author, etc., tokens come into the
 
24
          client with an svn:entry: prefix, are filtered by libsvn_wc,
 
25
          and stored in .svn/entries.   We'll call the new entryprops
 
26
          "svn:entry:lock-token", "svn:entry:lock-owner",
 
27
          "svn:entry:lock-comment and "svn:entry:lock-creation-date".
 
28
          (In DAV parlance, what
 
29
          we call 'entryprops' are called 'live props'.)
 
30
 
 
31
          libsvn_wc stores the other fields of a lock (owner,
 
32
          comment, creation-date) in the entries file, so that they
 
33
          are available for the info command.  Note that this
 
34
          information is only stored if the current WC has a lock on
 
35
          the file.
 
36
 
 
37
      2. New client subcommands
 
38
          
 
39
         a. Creating a lock
 
40
 
 
41
             'svn lock' calls new RA->lock() function, which marshals
 
42
             BASE rev of file to svn_fs_lock().  FS does a
 
43
             complimentary out-of-dateness check before creating the
 
44
             lock.  The lock is marshaled back to client, stored in
 
45
             .svn/entries file.
 
46
 
 
47
         b. Using a lock
 
48
 
 
49
            1. Using a lock to Commit
 
50
 
 
51
               A new RA layer get_commit_editor2() function will be created.
 
52
               It takes a hash of path -> lock token from the working
 
53
               copy.  This will be used by the server to check that
 
54
               the WC locks match the current locks on the paths.  A
 
55
               flag keep_locks will also be added, specifying whether
 
56
               the committables should be unlocked after a successful commit.
 
57
 
 
58
               libsvn_client will collect lock tokens during the
 
59
               harvesting of commit items.  If --no-unlock was not
 
60
               specified, unmodified objects will be treated as commit
 
61
               items if the WC has a lock on them.  A new status flag
 
62
               in svn_client_commit_info_t indicates that the object
 
63
               has a lock token.
 
64
 
 
65
               A new svn_wc_process_committed2 WC function will be
 
66
               created with a flag indicating whether the lock toke
 
67
               should be removed as part of the post-commit entry update.
 
68
 
 
69
            2. Releasing a lock
 
70
 
 
71
               svn unlock uses the lock token stored in the WC and
 
72
               issues an ra->unlock command to the server.
 
73
 
 
74
 
 
75
         c. Breaking a lock
 
76
 
 
77
            svn unlock --force will first ask the server for a lock
 
78
            token and use it in the ra->unlock command to break the
 
79
            lock.
 
80
 
 
81
         d. Stealing a lock
 
82
 
 
83
            svn lock --force uses ra->lock with the force argument set
 
84
            to TRUE to steal a lock.
 
85
 
 
86
         e. Discovering/examining locks
 
87
 
 
88
            1. seeing lock tokens in a working copy
 
89
 
 
90
               The client uses the lock information stored in the
 
91
               entries file to show lock information with svn info and
 
92
               svn status.
 
93
 
 
94
            2. seeing locks in a repository
 
95
 
 
96
               The server will marshal the lock information as
 
97
               entryprops when calling the status editor.
 
98
 
 
99
               svn info URL will use RA->get_lock to get the lock for the
 
100
               path specified.
 
101
 
 
102
            3. 'svn update' behavior
 
103
 
 
104
                A.  At the start of an update, a new version of the
 
105
                'reporter' vtable is used to describe not only mixed
 
106
                revnums to the server, but also existing locktokens.
 
107
                We need to be careful with protocols when marshaling
 
108
                this new information to older or newer servers.
 
109
 
 
110
                In ra_svn a new command will be added to the report
 
111
                command set for this purpose.
 
112
 
 
113
                B.  If a locktoken is defunct (expired, broken,
 
114
                whatever), then the server sends a 'deletion' of the
 
115
                locktoken entryprop, through normal means: the prop
 
116
                deletion comes into the update_editor, and thus is
 
117
                removed from .svn/entries.
 
118
 
 
119
 
 
120
III. Server Implementation
 
121
 
 
122
   A. Overview
 
123
 
 
124
   B. Tracking locks
 
125
 
 
126
      1. Define a lock-token:
 
127
 
 
128
            UUID
 
129
            owner
 
130
            comment [optional]
 
131
            creation-date
 
132
            expiration-date [optional]
 
133
 
 
134
      2. Define a lock-table that maps [fs-path --> lock-token]
 
135
 
 
136
         Beware the "deletion problem": if a certain path is locked,
 
137
         then no parent directory of that path can be deleted.
 
138
 
 
139
         The bad way to solve this problem is to do an O(N) recursive
 
140
         search of the directory being deleted, making sure no child
 
141
         is locked.
 
142
 
 
143
         The good way to solve this problem is to implement the 'lock
 
144
         table' as a tree.  When an object is locked, we create the
 
145
         locked path in the lock-tree.  Then, the mere existence of a
 
146
         directory in the lock-tree means it has at least one locked
 
147
         child, and cannot be deleted.  This is a much more acceptable
 
148
         O(logN) search.
 
149
 
 
150
   C.  How to implement locks in libsvn_fs
 
151
 
 
152
          This option implies that both BDB and FSFS would need to
 
153
          implement the 'lock tree' in their own way.  Any user of
 
154
          libsvn_fs would automatically get lock-enforcement.
 
155
 
 
156
 
 
157
      1.  Define an API for associating a user with an open
 
158
          filesystem.  Locks cannot be created/destroyed without a
 
159
          username, except that the filesystem allows breaking a lock
 
160
          without a username.
 
161
 
 
162
      2.  New fs functions for locks:
 
163
 
 
164
              svn_fs_lock()       --> locks a file
 
165
              svn_fs_unlock()     --> unlocks a file
 
166
              svn_fs_get_locks()  --> returns list of locked paths
 
167
              svn_fs_get_lock()   --> discover if a path is locked
 
168
 
 
169
            These functions don't do anything special, other than
 
170
            allow one to create/release/examine locks.  BDB and FSFS
 
171
            need to implement these functions independently.
 
172
 
 
173
      3.  Wrap two of the functions in libsvn_repos, to invoke hooks.
 
174
 
 
175
              svn_repos_fs_lock()
 
176
              svn_repos_fs_unlock()
 
177
 
 
178
            As usually, encourage "good citizens" to use these
 
179
            wrappers, since they'll invoke the new hook scripts.  The
 
180
            only thing which calls the fs functions directly (and
 
181
            circumvents hooks) would be a tool like svnadmin (see
 
182
            'svnadmin unlock' in UI document.)
 
183
 
 
184
      4.  Teach a number of fs functions to check for locks, and deal
 
185
          with them:
 
186
 
 
187
          svn_fs_node_prop()
 
188
          svn_fs_apply_textdelta()
 
189
          svn_fs_apply_text()
 
190
          svn_fs_make_file()
 
191
          svn_fs_make_dir()
 
192
 
 
193
            Check to see if the incoming path is locked.  If so, use
 
194
            the access descriptor to see if the caller has the lock token.
 
195
 
 
196
              1. check that the lock-token correctly matches the
 
197
                 lock. (i.e. that the caller isn't using some defunct
 
198
                 or malformed token).
 
199
 
 
200
              2. check that the lock owner matches whatever
 
201
                 authenticated username is currently attached to the fs.
 
202
 
 
203
          svn_fs_copy()
 
204
          svn_fs_revision_link()
 
205
          svn_fs_delete()
 
206
 
 
207
            Same logic as above, except that because these operations
 
208
            can operate on entire trees,  *multiple* lock-tokens might
 
209
            need to be checked in the access descriptor.
 
210
 
 
211
          svn_fs_commit_txn()
 
212
 
 
213
            Same logic, but this is the "final" check.  This function
 
214
            already briefly locks the revisions-table in order to do a
 
215
            final out-of-date check on everything.  In that same vein,
 
216
            it needs to briefly lock the locks-table, and verify every
 
217
            single lock.
 
218
 
 
219
 
 
220
      5.  auto-expiration of locks
 
221
 
 
222
          The common code which reads locks should be implemented in a
 
223
          special way: whenever a lock is read, lock expiration should
 
224
          be checked.  If a lock has expired, then the lock should be
 
225
          removed, and the caller (doing the read operation) should
 
226
          get nothing back.
 
227
 
 
228
          As discussed on the list -- the svn_fs_lock() command should
 
229
          take an optional argument for the 'expiration-date' field.
 
230
          But this field should *never* be used by anything other than
 
231
          mod_dav_svn responding to generic DAV clients.  We don't
 
232
          want to expose this feature to the svn client.
 
233
 
 
234
 
 
235
 
 
236
   D. Configurable Mechanisms
 
237
 
 
238
      1. New "pre-" hook scripts
 
239
 
 
240
        a. pre-lock
 
241
 
 
242
        b. pre-unlock
 
243
 
 
244
      2. New "post-" hook scripts
 
245
 
 
246
        a. post-lock
 
247
 
 
248
        b. post-unlock
 
249
 
 
250
 
 
251
   E. Lock manipulation with server tools
 
252
 
 
253
      1. 'svnlook listlocks'
 
254
 
 
255
      2. 'svnadmin unlock'
 
256