(See also common preferences panel help.)

Using the Grail Cache

About the cache

Grail uses a persistent disk cache to reduce the cost of loading resources across the network. In many cases, a copy of the resource is kept on your local disk so that future access can use the local copy instead of making a network connection. Resources like HTML pages and in-line images are good candidates for caching.

Grail is conservative about making caching decisions: It does not, for example, cache resources that are created dynamically and it allows you to specify how long a resource should stay in the cache before a new copy is retrieved. Under the factory default settings, the cache stores 1 megabyte of recently used data in your .grail directory.

There is a detailed discussion of how Grail caches items below. If you suspect that your browser is displaying a cached resource that is out of date, you can always use the Reload command to force Grail to retrieve a new copy.

Preferences for controlling the cache

Size
The maximum amount of data that can be stored in the cache. If a new resource is loaded and the cache is already full, an older resource is deleted from the cache. (Also see the note below about the size of the cache's log.)
Directory
The directory where cached resources are stored. If the directory's path is not absolute, it is interpreted as being relative to your .grail directory.
When you change cache directories, the old directory and its cached resources are preserved and the new directory is checked for an existing cache. If no cache is found in the new directory, a new one is created. (Thus, you could have two different caches and switch between them.)
Erase cache now
Clicking this button will erase the entire contents of the current cache directory and start a new cache.
Repair cache
Grail keeps a log of all the resources in the cache (in a text file called 'LOG'). Under unusual circumstances, it is possible that a resource will be stored in the cache directory but will not be listed in the log; this wastes disk space, but shouldn't have any other ill effects. Clicking the repair button will delete any file in the cache directory that isn't listed in the log.
This "lost file" problem is only known to occur when you run more the own Grail process simultaneously. (But you probably don't want to do that; see the note below.)
Verify document
The verify document preference controls what Grail does to ensure that the cached resources are kept up-to-date. When Grail verifies a document, it sends a standard HTTP request that uses the 'If-Modified-Since' header to that asks the server to return a copy of the resource only if it has changed since the cached copy was made.
Verify: Always
Every time you look at a page, Grail checks with the server.
Verify: Once per session
A resource is checked the first time it is used during any session. (A session starts when you start a new Grail process or when you changed cache directories.)
Verify: Never
Always assume that the cached copy is up-to-date. To get a new copy of the resource from the server, you must use the Reload command.
Verify: Ever Q hours
Check with the server if more than Q hours have elapsed since the last time the server was asked about a particular resource. (Q can be a fractional part of an hour.)

Detailed explanation of caching decisions

Caching World Wide Web resources introduces a number of complexities that can make it difficult to determine if the page you see in your browser is the same as the page that is currently on the original server. (Proxy servers that implement caching further complicates the issue.) The following lists provides a detailed discussion of how Grail decides when to cache objects and what steps it takes to verify that cached copies of resources are not out-of-date. When to cache an object?

Warnings and bugs