README

   1 Cache algorithm
   2 ===============
   3
   4 Cgit normally returns cached pages when invoked. If there is no cache file, or
   5 the cache file has expired, it is regenerated. Finally, the cache file is
   6 printed on stdout.
   7
   8 When it is decided that a cache file needs to be regenerated, an attempt is
   9 made to create a corresponding lockfile. If this fails, the process gives up
  10 and uses the expired cache file instead.
  11
  12 When there is no cache file for a request, an attempt is made to create a
  13 corresponding lockfile. If this fails, the process calls sched_yield(2) before
  14 restarting the request handling.
  15
  16 In pseudocode:
  17
  18         name = generate_cache_name(request);
  19 top:
  20         if (!exists(name)) {
  21                 if (lock_cache(name)) {
  22                         generate_cache(request, name);
  23                         unlock_cache(name);
  24                 } else {
  25                         sched_yield();
  26                         goto top;
  27                 }
  28         } else if (expired(name)) {
  29                 if (lock_cache(name)) {
  30                         generate_cache(request, name);
  31                         unlock_cache(name);
  32                 }
  33         }
  34         print_file(name);
  35
  36
  37 The following options can be set in /etc/cgitrc to control cache behaviour:
  38   cache-root:        root directory for cache files
  39   cache-root-ttl:    TTL for the repo listing page
  40   cache-repo-ttl:    TTL for any repos summary page
  41   cache-dynamic-ttl: TTL for pages with symbolic references (not SHA1)
  42   cache-static-ttl:  TTL for pages with sha1 references
  43
  44 TTL is specified in minutes, -1 meaning "infinite caching".
  45
  46
  47 Naming of cache files
  48 ---------------------
  49 Repository listing:  <cachedir>/index.html
  50 Repository summary:  <cachedir>/<repo>/index.html
  51 Repository subpage:  <cachedir>/<repo>/<page>/<querystring>.html
  52
  53 The corresponding lock files have a ".lock" suffix.
  54