Describe the cache's scan files and its locking

The background rebuild points its stderr at /dev/null so the web server
does not wait on it, which is why its failures never reach the log.

1 file changed, 13 insertions, 7 deletions

diff --git a/MANUAL.txt b/MANUAL.txtindex e3da45f..18c5129 100644--- a/MANUAL.txt+++ b/MANUAL.txt@@ -921,13 +921,19 @@ will be cached indefinitely, even if the underlying git repository changes. Conversely, when a ttl value is zero, the cache is disabled for that particular page type. A response larger than "cache-max-slot-size" is served but not kept. -The cache directory holds one file per slot plus transient lock files, all-created by cgit itself. Create the directory ahead of time, owned by the account-the web server runs cgit as, with mode 0700. cgit creates its files by name-without guarding against links planted beside them, so a directory other-accounts can write to would let those accounts redirect the writes. A directory-other accounts can read exposes every cached page along with the urls visitors-asked for.+The cache directory holds one file per slot and the cached results of scan-path+as rc-* files, plus transient lock files, all created by cgit itself. Create the+directory ahead of time, owned by the account the web server runs cgit as, with+mode 0700. cgit creates its files by name without guarding against links planted+beside them, so a directory other accounts can write to would let those accounts+redirect the writes. A directory other accounts can read exposes every cached+page along with the urls visitors asked for.++A slot or a scan result is rebuilt only by the process holding an flock on its+lock file. A request that finds the lock held serves the expired copy, or goes+without the cache when there is none, and logs nothing. Any other failure to+open, lock or write a lock file is logged with its path, apart from one in the+background rebuild of an expired scan result, whose output is discarded.   Signatures
diff --git a/MANUAL.txt b/MANUAL.txt
index e3da45f..18c5129 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -921,13 +921,19 @@ will be cached indefinitely, even if the underlying git repository changes.
 Conversely, when a ttl value is zero, the cache is disabled for that particular
 page type. A response larger than "cache-max-slot-size" is served but not kept.
 
-The cache directory holds one file per slot plus transient lock files, all
-created by cgit itself. Create the directory ahead of time, owned by the account
-the web server runs cgit as, with mode 0700. cgit creates its files by name
-without guarding against links planted beside them, so a directory other
-accounts can write to would let those accounts redirect the writes. A directory
-other accounts can read exposes every cached page along with the urls visitors
-asked for.
+The cache directory holds one file per slot and the cached results of scan-path
+as rc-* files, plus transient lock files, all created by cgit itself. Create the
+directory ahead of time, owned by the account the web server runs cgit as, with
+mode 0700. cgit creates its files by name without guarding against links planted
+beside them, so a directory other accounts can write to would let those accounts
+redirect the writes. A directory other accounts can read exposes every cached
+page along with the urls visitors asked for.
+
+A slot or a scan result is rebuilt only by the process holding an flock on its
+lock file. A request that finds the lock held serves the expired copy, or goes
+without the cache when there is none, and logs nothing. Any other failure to
+open, lock or write a lock file is logged with its path, apart from one in the
+background rebuild of an expired scan result, whose output is discarded.
 
 
 Signatures