about summary refs log tree commit diff stats
path: root/README
diff options
context:
space:
mode:
authorLars Hjemli2006-12-13 02:06:29 +0100
committerLars Hjemli2006-12-13 02:06:29 +0100
commitdcef257d4fdbb2e0ff645bf0524cfca652e65ff0 (patch)
tree08dea5dece7859d42fc5b876e5b6bcc1970c9bde /README
parentSmall layout adjustments to summary and blob view (diff)
downloadcgit-dcef257d4fdbb2e0ff645bf0524cfca652e65ff0.tar.gz
cgit-dcef257d4fdbb2e0ff645bf0524cfca652e65ff0.zip
Remove implementation details from README
Let README describe the "bigger picture" instead.

Signed-off-by: Lars Hjemli <hjemli@gmail.com>
Diffstat (limited to 'README')
-rw-r--r--README87
1 files changed, 34 insertions, 53 deletions
diff --git a/README b/README index 5917c37..010dd5c 100644 --- a/README +++ b/README
@@ -1,54 +1,35 @@
1Cache algorithm
2===============
3
4Cgit normally returns cached pages when invoked. If there is no cache file, or
5the cache file has expired, it is regenerated. Finally, the cache file is
6printed on stdout.
7
8When it is decided that a cache file needs to be regenerated, an attempt is
9made to create a corresponding lockfile. If this fails, the process gives up
10and uses the expired cache file instead.
11
12When there is no cache file for a request, an attempt is made to create a
13corresponding lockfile. If this fails, the process calls sched_yield(2) before
14restarting the request handling.
15
16In pseudocode:
17
18 name = generate_cache_name(request);
19top:
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
37The 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
44TTL is specified in minutes, -1 meaning "infinite caching".
45
46
47Naming of cache files
48---------------------
49Repository listing: <cachedir>/index.html
50Repository summary: <cachedir>/<repo>/index.html
51Repository subpage: <cachedir>/<repo>/<page>/<querystring>.html
52
53The corresponding lock files have a ".lock" suffix.
54 1
2 cgit - cgi for git
3
4
5This is an attempt to create a fast web interface for the git scm, using a
6frontside cache to decrease server io-pressure.
7
8When cgit is invoked, it looks for a cached page matching the request. If no
9such cachefile exist (or it has expired), it is (re)generated. Finally, the
10cachefile is returned to the client.
11
12If the cachefile has expired, but cgit is unable to lock the cachefile, the
13client will get the stale cachefile after all. This is done to favour page
14throughput over page freshness.
15
16Also, when a cachefile is generated, a few cache-related http-headers are
17created: "Modified" is set to current time(2), while "Expires" is set to
18time(2) + <cachefile TTL> * 60 (unless the TTL is negative, in which case it
19is read as "60 * 60 * 24 * 365"). This is done to avoid repeated requests for
20already visited pages.
21
22The 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
30The cachefiles are split into different directories, based on the requested
31repository and page:
32
33 Repo listing: <cachedir>/index.html
34 Repo summary: <cachedir>/<repo>/index.html
35 Repo subpage: <cachedir>/<repo>/<page>/<querystring>.html