summaryrefslogtreecommitdiffabout
path: root/README
Side-by-side diff
Diffstat (limited to 'README') (more/less context) (show whitespace changes)
-rw-r--r--README54
1 files changed, 54 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..5917c37
--- a/dev/null
+++ b/README
@@ -0,0 +1,54 @@
+Cache algorithm
+===============
+
+Cgit normally returns cached pages when invoked. If there is no cache file, or
+the cache file has expired, it is regenerated. Finally, the cache file is
+printed on stdout.
+
+When it is decided that a cache file needs to be regenerated, an attempt is
+made to create a corresponding lockfile. If this fails, the process gives up
+and uses the expired cache file instead.
+
+When there is no cache file for a request, an attempt is made to create a
+corresponding lockfile. If this fails, the process calls sched_yield(2) before
+restarting the request handling.
+
+In pseudocode:
+
+ name = generate_cache_name(request);
+top:
+ if (!exists(name)) {
+ if (lock_cache(name)) {
+ generate_cache(request, name);
+ unlock_cache(name);
+ } else {
+ sched_yield();
+ goto top;
+ }
+ } else if (expired(name)) {
+ if (lock_cache(name)) {
+ generate_cache(request, name);
+ unlock_cache(name);
+ }
+ }
+ print_file(name);
+
+
+The following options can be set in /etc/cgitrc to control cache behaviour:
+ cache-root: root directory for cache files
+ cache-root-ttl: TTL for the repo listing page
+ cache-repo-ttl: TTL for any repos summary page
+ cache-dynamic-ttl: TTL for pages with symbolic references (not SHA1)
+ cache-static-ttl: TTL for pages with sha1 references
+
+TTL is specified in minutes, -1 meaning "infinite caching".
+
+
+Naming of cache files
+---------------------
+Repository listing: <cachedir>/index.html
+Repository summary: <cachedir>/<repo>/index.html
+Repository subpage: <cachedir>/<repo>/<page>/<querystring>.html
+
+The corresponding lock files have a ".lock" suffix.
+