TestCache(1)

Name

TestCache - a client for testing the Vesta-2 cache server

Synopsis

TestCache [ -comments ] [ file ]

Description

TestCache reads a description of function arguments and results from the file named file, or from standard input if no file is specified. For each function described in the input, it performs a lookup or other function on the cache server running on the Vesta-2 cache server VCache(1) named in the user's Vesta configuration file, as described below. If the lookup fails, it makes the necessary calls to add a new entry to the cache. There are also commands for exercising the cache server's weeder interface, to checkpoint the contents of the cache, or to pause the TestCache program until the user presses a key.

If the -comments option is specified, all comments in the input file are echoed to standard output.

Input File Format

The input supplied to TestCache consists of a sequence of entries. There are several kinds of entries: function specifications, checkpoint commands, renew leases commands, pause commands, and weeder commands. Comments are indicated in the input by lines that start with the percent (%) character; all characters from the percent character up to (and including) the next newline character are ignored. Blank lines are also ignored.

Function Specifications

A function specification describes a function, its arguments, and its result. It takes the following form:

primary-key-text
name-1 name-2 ... name-n
fp-1 fp-2 ... fp-n
result-text

The test program computes the fingerprint of the primary-key-text, and uses that fingerprint as the function's primary key. The name-i are whitespace-separated strings; they are the names of the function's free variables. The fp-i are used to compute the fingerprints of the free variables. The fp-i are texts; the fingerprint of each text is computed and used as the fingerprint for the corresponding name-i. Finally, the result-text is used as the function result.

Given a function specification, the TestCache program performs the following steps:

1. TestCache computes the fingerprint corresponding to primary-key-text to produce a primary key PK.

2. It then calls the cache server's FreeVariables method with the argument PK, and receives the list of free variables corresponding to PK from the cache server.

3. It then calls the cache server's Lookup method, supplying the fingerprints of the names returned in the previous step. For each name in that list that matches one of the names name-i, it gets the fingerprint of that name's value from fp-i. For each requested name that is not one of the name-i, it supplies the fingerprint of the empty string.

4. If the Lookup call produces a hit from the cache, the processing of this function specification is complete. Otherwise, TestCache makes a call to the cache server's AddEntry method to add a new cache entry.

Checkpoint Commands

A checkpoint command consists of a single line of the form:

Checkpoint

or

CheckpointOnly

TestCache processes a Checkpoint command by calling the cache server's Checkpoint method with an empty list of cache indices, and a done value of true. It then calls the cache server's FlushAll method to flush all new, pending cache entries to the stable cache.

The CheckpointOnly command is like the Checkpoint command except that it does not invoke the cache server's FlushAll method.

Renew Leases Command

A renew leases command consists of lines of the form:

RenewLeases
ci-1 ci-2 ... ci-n

This invokes the cache server's RenewLeases method with the named cache indices as arguments.

Pause Commands

A pause command conists of a single line of the form:

Pause

TestCache processes a pause command by prompting the user to press a key to continue. A pause command is usually used immediately after a checkpoint command. While the program is paused, you can check that the files written by the cache server are correct before you continue the test.

Weeder Commands

Weeder commands take the following form:

Weed
ci-1 ci-2 ... ci-n
pfx-1 pfx-2 ... pfx-l

These commands actually invoke four separate methods on the cache server: StartMark, SetHitFilter, ResumeLeaseExp, and EndMark.

The ci list specifies the indices of the cache entries to delete. The pfx list is a list of texts analogous to the primary-key-texts of the function specifications above. The fingerprints of these texts are computed, then a prefix of each resulting fingerprint is computed. The set of resulting prefixes names the MultiPKFiles that contain all of the entries to delete.

Example

Here is a sample input file:

func1
name1 name2 name3
val1  val2  val3
result1

func1
name2 name4 name3
val2  val4  val3
result2

Checkpoint

func1
name3 name5 name2
val4  val5  val3
result3

func1
name3 name1 name2
val3  val1  val2
dummy-result

Checkpoint

Only the very last function specification will produce a hit on the cache. After processing this file, there will be three cache entries for func1, and its common names will be name2 and name3.

Configuration Variables

Like most Vesta-2 applications, TestCache reads site-specific configuration information from a Vesta-2 configuration file named vesta.cfg. The program first looks for this file in the current directory; if none is found there, it looks in your home directory.

The configuration file is divided into a number of sections, denoted in the file by [SectionName]. The variables used by TestCache are in the section denoted by [CacheServer]. Here are the variables and their meanings; the types of the variables are shown in parentheses.

Host (string)

The hostname of the machine on which the cache server is running.

Port (integer)

The port number on the host named by Host to contact. This allows multiple cache servers to be running on the same machine; each one listens on a different port for connections.

See Also

VCache(1), ChkptCache(1), TestCacheRandom(1)

Author

Allan Heydon (caheydon@yahoo.com)

Last modified on Thu Nov  8 12:40:15 EST 2001 by ken@xorian.net
     modified on Fri Feb 28 10:50:43 PST 1997 by heydon