three meanings of "lock" [PATCH]
Gareth McCaughan
gareth.mccaughan at pobox.com
Mon Jan 23 15:03:58 CST 2006
I wrote:
> So, here's a patch.
Only there wasn't, because I'm an idiot. Thanks to Ben C-S
for drawing my attention to my goof.
Working directory for the patch, in case it isn't obvious:
trunk/src/en .
---------- patch begins ----------
Index: book/ch03.xml
===================================================================
--- book/ch03.xml (revision 1946)
+++ book/ch03.xml (working copy)
@@ -1063,8 +1063,10 @@
switch</command>) to a branch.</para>
<para>The sixth column shows information about locks, which is
- further explained in <xref
- linkend="svn.advanced.locking"/>.</para>
+ further explained in <xref linkend="svn.advanced.locking"/>.
+ (These are not the same locks as the ones indicated by an
+ <computeroutput>L</computeroutput> in the third column;
+ see <xref linkend="svn.advanced.locking.meanings"/>.)</para>
<para>If you pass a specific path to <command>svn
status</command>, it gives you information about that item
@@ -2152,7 +2154,10 @@
information within <filename>.svn</filename>), it tries to do
so as safely as possible. Before changing the working copy,
Subversion writes its intentions to a log file. Next it executes
- the commands in the log file to apply the requested change.
+ the commands in the log file to apply the requested change,
+ holding a lock on the relevant part of the working copy while
+ it does so to prevent other Subversion clients trying to
+ access the working copy in mid-change.
Finally, Subversion removes the log file. Architecturally, this
is similar to a journaled filesystem. If a Subversion operation is
interrupted (if the process is killed, or if the machine
@@ -2163,9 +2168,9 @@
<para>And this is exactly what <command>svn cleanup</command>
does: it searches your working copy and runs any leftover
- logs, removing locks in the process. If Subversion ever tells
- you that some part of your working copy is
- <quote>locked</quote>, then this is the command that you
+ logs, removing working copy locks in the process.
+ If Subversion ever tells you that some part of your working copy
+ is <quote>locked</quote>, then this is the command that you
should run. Also, <command>svn status</command> will display
an <literal>L</literal> next to locked items:</para>
@@ -2179,6 +2184,13 @@
M somedir/foo.c
</screen>
+ <para>Don't confuse these working copy locks with the
+ ordinary locks that Subversion users create when
+ using the <quote>lock-modify-unlock</quote> model
+ of concurrent version control; see <xref
+ linkend="svn.advanced.locking.meanings"/>
+ for clarification.</para>
+
</sect2>
Index: book/ch05.xml
===================================================================
--- book/ch05.xml (revision 1946)
+++ book/ch05.xml (working copy)
@@ -902,7 +902,7 @@
<para>A Berkeley DB environment is an encapsulation of one or
more databases, log files, region files and configuration
files. The Berkeley DB environment has its own set of default
- configuration values for things like the number of locks
+ configuration values for things like the number of database locks
allowed to be taken out at any given time, or the maximum size
of the journaling log files, etc. Subversion's filesystem
code additionally chooses default values for some of the
@@ -2070,7 +2070,10 @@
data, makes the change it wants to make, and then unlocks the
data. Other processes are forced to wait until that lock is
removed before they are permitted to continue accessing that
- section of the database.</para>
+ section of the database. (This has nothing to do with the
+ locks you, as a user, can apply to the repository; see
+ <xref linkend="svn.advanced.locking.meanings"/> for more
+ information.)</para>
<para>In the course of using your Subversion repository, fatal
errors (such as running out of disk space or available memory)
Index: book/ch07.xml
===================================================================
--- book/ch07.xml (revision 1946)
+++ book/ch07.xml (working copy)
@@ -1811,6 +1811,43 @@
only—it's not yet possible to reserve access to a whole
directory tree.</para>
+ <sidebar id="svn.advanced.locking.meanings">
+ <title>Three meanings of <quote>lock</quote></title>
+
+ <para>In this section, and almost everywhere in this book,
+ the words <quote>lock</quote> and <quote>locking</quote>
+ describe a mechanism for mutual exclusion between users,
+ to avoid clashing commits. Unfortunately, there are two
+ other sorts of <quote>lock</quote> with which Subversion,
+ and therefore this book, sometimes needs to be concerned.</para>
+
+ <itemizedlist>
+ <listitem><para><firstterm>Working copy locks</firstterm>,
+ used internally by Subversion to prevent clashes
+ between multiple Subversion clients operating on
+ the same working copy. This is the sort of lock
+ indicated by an <computeroutput>L</computeroutput>
+ in the third column of <command>svn status</command>
+ output, and removed by the <command>svn cleanup</command>
+ command, as described in <xref
linkend="svn.tour.other.cleanup"/>.</para>
+ </listitem>
+ <listitem><para><firstterm>Database locks</firstterm>,
+ used internally by the Berkeley DB backend to prevent
+ clashes between multiple programs trying to access the
+ database. This is the sort of lock whose unwanted
+ persistence after an error can cause a repository
+ to be <quote>wedged</quote>, as described in
+ <xref linkend="svn.reposadmin.maint.recovery"/>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You can generally forget about these other sorts of lock,
+ until something goes wrong that requires you to care about
+ them. In this book, <quote>lock</quote> means the first sort
+ unless the contrary is either clear from context or explicitly
+ stated.</para>
+ </sidebar>
+
<!-- =============================================================== -->
<sect2 id="svn.advanced.locking.creation">
<title>Creating locks</title>
Index: book/ch09.xml
===================================================================
--- book/ch09.xml (revision 1946)
+++ book/ch09.xml (working copy)
@@ -908,9 +908,9 @@
<title>Description</title>
<para>Recursively clean up the working copy, removing
- locks resuming unfinished operations. If you ever get a
- <quote>working copy locked</quote> error, run this
- command to remove stale locks and get your working copy
+ working copy locks and resuming unfinished operations.
+ If you ever get a <quote>working copy locked</quote> error,
+ run this command to remove stale locks and get your working copy
into a usable state again.</para>
<para>If, for some reason, an <command>svn update</command>
@@ -3483,7 +3483,8 @@
</variablelist>
<para>The third column is populated only if the
- working copy directory is locked.</para>
+ working copy directory is locked. (See
+ <xref linkend="svn.tour.other.cleanup"/>.)</para>
<variablelist>
@@ -3990,7 +3991,9 @@
synchronizes the working copy to the revision given by the
<option>--revision</option> switch. As part of the
synchronization, <command>svn update</command> also
- removes any stale locks found in the working copy.</para>
+ removes any stale locks (see <xref
+ linkend="svn.tour.other.cleanup"/>) found in the
+ working copy.</para>
<para>For each updated item a line will start with a
character reporting the action taken. These characters
@@ -4746,9 +4749,10 @@
</screen>
<para>Recovering the database requires an exclusive lock on
- the repository. If another process is accessing the
- repository, then <command>svnadmin recover</command> will
- error:</para>
+ the repository. (This is a <quote>database lock</quote>;
+ see <xref linkend="svn.advanced.locking.meanings"/>.)
+ If another process is accessing the repository,
+ then <command>svnadmin recover</command> will error:</para>
<screen>
$ svnadmin recover /usr/local/svn/repos
svn: Failed to get exclusive repository access; perhaps another process
---------- patch ends ----------
--
g
More information about the svnbook-dev
mailing list