Rev 5538: Fix some spelling mistakes and start explaining the new locking scheme a bit better. in file:///home/vila/src/bzr/experimental/config/

Vincent Ladeuil v.ladeuil+lp at free.fr
Mon Apr 4 08:33:02 UTC 2011


At file:///home/vila/src/bzr/experimental/config/

------------------------------------------------------------
revno: 5538
revision-id: v.ladeuil+lp at free.fr-20110404083302-1eupx4k52va5mfsd
parent: v.ladeuil+lp at free.fr-20110331153701-qtx9frnrktsnfgql
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: doc-new-config
timestamp: Mon 2011-04-04 10:33:02 +0200
message:
  Fix some spelling mistakes and start explaining the new locking scheme a bit better.
-------------- next part --------------
=== modified file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt	2011-03-31 15:37:01 +0000
+++ b/doc/developers/configuration.txt	2011-04-04 08:33:02 +0000
@@ -94,7 +94,7 @@
 * Since sections allow different definitions for the same option, a total
   order should be defined between sections to select the right definition for
   a given context (paths or globs for ``locations.conf`` but other schemes can
-  be used, window names for qbzr for exmaple). Allowing globs for section
+  be used, window names for qbzr for example). Allowing globs for section
   names is harmful in this respect since the order is currently defined as
   being the lexicographical one. The caveat here is that if the order is
   always defined for a given set of sections it can change when one or several
@@ -278,7 +278,7 @@
 
 In addition to the configuration files, one internal configuration dict can
 contain definitions for some configuration options. This will allow a finer
-grained definition of the default values and the online help.
+grained definition of the default values and the on-line help.
 
 The ConfigOption object will define:
 
@@ -286,7 +286,7 @@
 
 * default value. ``None`` is the "default" default value.
 
-* docstring used for the help
+* doc-string used for the help
 
 * a list of config files where the option can be defined.
 
@@ -380,7 +380,7 @@
 
   The options related to the branch.
 
-  Sections can be defined for co-located branches or loom threads.
+  Sections can be defined for colocated branches or loom threads.
 
 * repo.conf (Not Implemented Yet)
 
@@ -587,3 +587,77 @@
 
 The modifications will be made to the section in branch.conf specified when
 building the branch config object (generally the default section).
+
+Why and when locking config files matter
+----------------------------------------
+
+bzr behavior, as well as the objects it acts upon, are configured
+via a set of so-called configuration files.
+
+These files allow to define working trees, branches and
+repositories, their relationships and how bzr should handle them.
+
+The default behavior of bzr is aimed at making this configuration
+as transparent as possible by keeping track of how these objects
+are created and modified when they are used. In short, they are
+useless until you want to change the default behavior in some
+specific context.
+
+We mostly **read** config options. Therefore all we care about is
+to guarantee that:
+
+* we get a valid config file at all times when reading,
+
+* we always leave a valid config file when writing (via the rename dance)
+
+From there, conceptually, all operations can clearly define
+whether or not they need to modify a config file and do so only
+when they succeed. All modifications occurring during such an
+operation are delayed until the very end of the operation.
+
+Now, we want to minimize the overlapping times where one bzr
+operation has changed a value and another concurrent operation is
+unaware of this modification.
+
+These overlapping periods are *as of today* rare.
+
+The only known case, bug #525571 has been fixed in bzr-2.1.3. The
+bug there was triggered when two processes tried to write the
+same config file at the same time leaving an invalid file in the
+end.
+
+Such a period can be recognized and detected though: when
+changing an option value, if the preserved original value is
+different in the config file, someone else modified it and the
+operation can be invalid because it relied on the original value.
+
+For the sake of the example, if an option value represent a
+global unique ID via a simple counter (very bad idea), if two
+operations try to increment it, both will use the same value that
+won't be unique anymore. Checking the value present in the file
+when trying to save the updated value with identify such a
+collision.
+
+An assumption is floating around: it should be enough to report
+when an operation is modifying an already modified option and
+observe that no-one reports such occurrences.
+
+Note that this assumption is made in a context where *no* known
+scenarios exist in the bzr code base not in any plugin (for a
+best effort value of 'any', feedback highly welcome, bug reports
+even ;)
+
+With this in mind, we can change the definition of config
+options, stores and stacks to ensure that:
+
+* a config file is read only once when in read access,
+
+* a config file is read only once and written only once when in
+  write access, adding the check mentioned above will require
+  *one* additional read.
+
+A reader can then safely assume that reading a config file gives
+it a valid (and coherent) definition of the configuration when
+the operation starts. All the operation has to do is to declare
+which config files may be modified by an operation (whether or
+not we can be liberal on this 'may be' is yet to be defined).



More information about the bazaar-commits mailing list