Note that servers of happiness only applies to immutable files for the moment

diff --git a/docs/architecture.txt b/docs/architecture.txt
index aa0101d1cd047b960970a4624d53b6226407381d..0451d4e9a0dbe37b75b51ce1ade2d652242b2090 100644 (file)
--- a/docs/architecture.txt
+++ b/docs/architecture.txt
@@ -195,17 +195,28 @@ that information to the share-to-server table. This lets us do less work for
 files which have been uploaded once before, while making sure we still wind up
 with as many shares as we desire.
 
-If we are unable to place every share that we want, but we still managed to
-place enough shares on enough servers to achieve a condition called "servers of
-happiness" then we'll do the upload anyways. If we cannot achieve "servers of
-happiness", the upload is declared a failure.
+Before a file upload is called successful, it has to pass an upload health
+check. For immutable files, we check to see that a condition called
+'servers-of-happiness' is satisfied. When satisfied, 'servers-of-happiness'
+assures us that enough pieces of the file are distributed across enough
+servers on the grid to ensure that the availability of the file will not be
+affected if a few of those servers later fail. For mutable files and
+directories, we check to see that all of the encoded shares generated during
+the upload process were successfully placed on the grid. This is a weaker
+check than 'servers-of-happiness'; it does not consider any information about
+how the encoded shares are placed on the grid, and cannot detect situations in
+which all or a majority of the encoded shares generated during the upload
+process reside on only one storage server. We hope to extend
+'servers-of-happiness' to mutable files in a future release of Tahoe-LAFS. If,
+at the end of the upload process, the appropriate upload health check fails,
+the upload is considered a failure.
 
 The current defaults use k=3, servers_of_happiness=7, and N=10. N=10 means that
 we'll try to place 10 shares. k=3 means that we need any three shares to
-recover the file. servers_of_happiness=7 means that we'll consider the upload
-to be successful if we can place shares on enough servers that there are 7
-different servers, the correct functioning of any k of which guarantee the
-availability of the file.
+recover the file. servers_of_happiness=7 means that we'll consider an immutable
+file upload to be successful if we can place shares on enough servers that
+there are 7 different servers, the correct functioning of any k of which
+guarantee the availability of the immutable file.
 
 N=10 and k=3 means there is a 3.3x expansion factor. On a small grid, you
 should set N about equal to the number of storage servers in your grid; on a

diff --git a/docs/configuration.txt b/docs/configuration.txt
index 0082011228ebafc16ce35b0407e82b3a1e548348..398ba1d983fb961db71270b25988d019dfa84033 100644 (file)
--- a/docs/configuration.txt
+++ b/docs/configuration.txt
@@ -272,11 +272,14 @@ shares.happy = (int, optional) k <= happy <= N
  larger than 256, because of the 8-bit erasure-coding algorithm that Tahoe
  uses.
 
- shares.happy allows you control over the distribution of your file. An upload
- is only considered successful if shares are placed on at least 'shares.happy'
- distinct servers, the correct functioning of at least k of which is sufficient
- to guarantee the availability of the uploaded file. This value should not be
- larger than the number of servers on your grid.
+ shares.happy allows you control over the distribution of your immutable file.
+ An upload is only considered successful if shares are placed on at least
+ 'shares.happy' distinct servers, the correct functioning of at least k of
+ which is sufficient to guarantee the availability of the uploaded file. This
+ value should not be larger than the number of servers on your grid.
+
+ (Mutable files use a different share placement algorithm that does not 
+  consider this parameter.)
 
 
 == Storage Server Configuration ==