Let README describe the "bigger picture" instead.
Unified · Split
| @@ -1,54 +1,35 @@ | ||
| 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 | 1 | |
| 2 | + cgit - cgi for git | |
| 3 | + | |
| 4 | + | |
| 5 | +This is an attempt to create a fast web interface for the git scm, using a | |
| 6 | +frontside cache to decrease server io-pressure. | |
| 7 | + | |
| 8 | +When cgit is invoked, it looks for a cached page matching the request. If no | |
| 9 | +such cachefile exist (or it has expired), it is (re)generated. Finally, the | |
| 10 | +cachefile is returned to the client. | |
| 11 | + | |
| 12 | +If the cachefile has expired, but cgit is unable to lock the cachefile, the | |
| 13 | +client will get the stale cachefile after all. This is done to favour page | |
| 14 | +throughput over page freshness. | |
| 15 | + | |
| 16 | +Also, when a cachefile is generated, a few cache-related http-headers are | |
| 17 | +created: "Modified" is set to current time(2), while "Expires" is set to | |
| 18 | +time(2) + <cachefile TTL> * 60 (unless the TTL is negative, in which case it | |
| 19 | +is read as "60 * 60 * 24 * 365"). This is done to avoid repeated requests for | |
| 20 | +already visited pages. | |
| 21 | + | |
| 22 | +The following cache-related options can be set in /etc/cgitrc: | |
| 23 | + | |
| 24 | + cache-root=<path> root directory for cache files | |
| 25 | + cache-root-ttl=<min> TTL for the repo listing page | |
| 26 | + cache-repo-ttl=<min> TTL for repo summary pages | |
| 27 | + cache-dynamic-ttl=<min> TTL for pages with symbolic references | |
| 28 | + cache-static-ttl=<min> TTL for pages with sha1 references | |
| 29 | + | |
| 30 | +The cachefiles are split into different directories, based on the requested | |
| 31 | +repository and page: | |
| 32 | + | |
| 33 | + Repo listing: <cachedir>/index.html | |
| 34 | + Repo summary: <cachedir>/<repo>/index.html | |
| 35 | + Repo subpage: <cachedir>/<repo>/<page>/<querystring>.html | |