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