VCache - the Vesta-2 function cache server


VCache [ -debug level ] [ -noHits ]



VCache is the Vesta-2 function cache server process. It keeps a persistent record of Vesta-2 function evaluations. The primary client of the function cache is the Vesta-2 evaluator vesta(1), which evaluates Vesta build descriptions, also known as models.

The function cache expects certain directories to exist, and creates files in those directories. To create the necessary directories, use the CreateCacheDirs(1) program. For information about the files written by VCache, see the Configuration Variables and Files sections below.


The function cache recognizes the following command-line options:

-debug level
By default, no debugging information is printed. However, the cache server has support for printing various kinds of debugging information. This debugging output is catagorized into various levels. All levels at and below the specified level will be printed. The possible values for level (in increasing order) are:

Don't print any debugging information. This is the default.

Print function cache status messages, such as a message when the cache server starts up and messages when clients disconnect. The startup message includes the name of the configuration file, the selected debugging levels, and the value for the MaxRunning configuration variable.

Print a message when leases on cache entries expire. The duration of cache entry leases is controlled by the LeaseTimeoutHrs configuration variable (described below). Cache entry leases are implemented as a pair of bit vectors, new and old. When a new lease is taken out on a cache entry, the corresponding bit is set in the new vector. A lease exists for a cache entry if its bit is set in either vector. To expire leases, a background thread repeatedly copies new to old and zeros out new. The lease debugging output shows a prefix of both vectors before they are expired. The bit vectors are printed in hex, a byte at a time, least significant byte first. When the vector is longer than 256 bits, the output is elided with ellipses.

Print a description of data recovered from the function cache's logs at start-up.

Print a message each time the flush of a function cache log is started or finished. The logs are typically flushed whenever a client invokes the function cache's Checkpoint method. At this debugging level, the values flushed to the logs are not printed; use the LogFlushEntries level below for that.

Print messages when volatile cache entries are flushed to the stable cache (namely, to stable MultiPKFiles).

Print (possibly elided versions of) the values written to the function cache's logs when they are flushed. The output in this case may be interspersed with other debugging output, but whole lines are guaranteed to be printed atomically.

Print the arguments and results of all weeder calls to the cache server.

Print the arguments and results of AddEntry calls to the cache server.

Print the arguments and results of all other calls to the cache server, including FreeVariables, Lookup, and Checkpoint.

Print all debugging information. This is equivalent to OtherOps.

Debugging output is grouped into logical entries. Each debugging output entry includes a timestamp, and debugging output is synchronized so that entries produced by different threads are not interleaved.

If -noHits is specified, the lookup operation on the cache will never produce a hit. This is useful for debugging clients of the function cache.

Configuration Variables

Like most Vesta-2 applications, the function cache reads site-specific configuration information from a Vesta-2 configuration file named vesta.cfg. The function cache 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 the function cache are in the section denoted by [CacheServer]. Here are the variables and their meanings; the types of the variables are shown in parentheses. Those variables corresponding to paths or directories should not end with a slash ("/") character.

The following variables are the function cache's operating parameters:

Port (integer)
The port number on which the server listens for connections.

Host (hostname)
The host on which the cache server runs. Used by clients to connect to the cache server.

MaxRunning (integer) (optional)
The maximum number of client requests that the function cache will handle at any given time. If this many requests are currently running and another is received, it will block. Defaults to 32.

MaxCacheLogCnt (integer) (optional)
Controls the frequency of attempts to clean the cache log. Whenever the cache log is flushed and the number of cache entries written to the cache log since it was last cleaned exceeds this value, the background cache log cleaner thread is signaled to clean the cache log. Defaults to 500 entries.

MPKFileFlushNum (integer) (optional)
Whenever a new cache entry is added to a MultiPKFile and the total number of new cache entries in that MultiPKFile exceeds this value, the MultiPKFile is flushed to disk by a background MultiPKFile flusher thread. Defaults to 20.

LeaseTimeoutHrs (integer)
A lower-bound (in hours) on the duration of cache entry leases.

FlushWorkerCnt (integer) (optional)
Controls the number of background threads initially allocated for flushing MultiPKFiles to disk. Certain cache activities, like the background MultiPKFile freeing thread (described below), and invocations of the CacheS::FlushAll method, block unless an idle worker thread is available. Hence, this variable controls how many MultiPKFiles the cache may be flushing concurrently as the result of certain operations. Defaults to 5.

FreePauseDur (integer)
The number of seconds that the background MultiPKFile/PKFile freeing/flushing thread sleeps between attempts to flush new cache entries to disk and free memory. When the MultiPKFile freeing thread wakes up, it attempts to flush new entries in MultiPKFiles that have not been recently accessed, thereby freeing memory consumed by those cache entries. It also frees memory by purging "warm" entries paged in from disk and freeing datat structures for PKFiles and MultiPKFiles that haven't been used recently. See the related FlushNewPeriodCnt, PurgeWarmPeriodCnt, EvictPeriodCnt, and FreeAggressively variables below.

FlushNewPeriodCnt (integer) (optional)
Each time the background freeing/flushing thread wakes up to do work, it increments an epoch. An MPKFile is considered "stale" (and hence, in need of being flushed), if it has not been had any entries added within FlushNewPeriodCnt epochs. Defaults to 1. (If this variable is not set and the older name FreePeriodCnt is set, it will be used, for backward compatibility.)

PurgeWarmPeriodCnt (integer) (optional)
Each time the background freeing/flushing thread wakes up to do work, it increments an epoch. A PKFile with no new entries waiting to be flushed to disk will have its "warm" entries (those paged in from disk) freed from memory if it hasn't been used by any client calls (FreeVariables, Lookup, AddEntry) in PurgeWarmPeriodCnt epochs. Defaults to FlushNewPeriodCnt plus 1.

EvictPeriodCnt (integer) (optional)
Each time the background freeing/flushing thread wakes up to do work, it increments an epoch. A PKFile with no new entries waiting to be flushed to disk and no "warm" entries paged in from disk will have its data structures removed from the cache (to free memory) if it hasn't been used by any client calls (FreeVariables, Lookup, AddEntry) in EvictPeriodCnt epochs. Defaults to PurgeWarmPeriodCnt plus 1.

FreeAggressively (integer) (optional)
By default, when the background MultiPKFile freeing thread wakes up, it increments the flush epoch, but goes back to sleep if there has been any activity on the cache since the thread originally went to sleep. If this variable is non-zero, the thread will attempt to flush stale MultiPKFiles even if there has been some load on the cache. Defaults to 0 (false).

KeepNewOnFlush, KeepOldOnFlush (integers) (optional)
These values control the policy that determines which cache entries are kept in memory when a PKFile is flushed (updated). The first controls what happens to new entries that are not yet saved on disk, and the second controls what happens to "old" entries that have been paged-in from disk. If non-zero, the entries are kept in memory; if zero, they are dropped for the garbage collector to reclaim. Both default to 0 (false).

Here are the function cache's file system variables:

MetaDataRoot (string)
The pathname of the directory in which the Vesta system's metadata is stored. If this variable is undefined, the current directory is used. Other configuration variables are interpreted relative to this path. The directories (relative to the MetaDataRoot/MetaDataDir) in which the function cache stores its cache log, graph log, cache index (CI), and weeded MPKFile logs, respectively.

MetaDataDir (string)
The directory (relative to the MetaDataRoot) in which the cache server's metadata is stored.

SCacheDir (string)
The directory (relative to the MetaDataRoot/MetaDataDir) in which the function cache stores cache entries.

CacheLogDir, EmptyPKLogDir, GraphLogDir, CILogDir, WeededLogDir (strings)
The directories (relative to the MetaDataRoot/MetaDataDir) in which the function cache stores its cache log, empty PKFile log, graph log, cache index (CI) log, and weeded MPKFile log, respectively.

StableVarsDir (string)
The directory (relative to the MetaDataRoot/MetaDataDir) in which the function cache stores files corresponding to its stable variables.

Deleting, HitFilter, MPKsToWeed (strings)
The files (relative to MetaDataRoot/MetaDataDir/StableVarsDir) corresponding to stable function cache variables.

The following configuration variables are for debugging purposes only:

LeaseTimeoutSpeedup (integer) (optional)
The factor by which the LeaseTimeoutHrs should be reduced. For example, if LeaseTimeoutHrs is 1 and LeaseTimeoutSpeedup is 120, then the cache entry leases will time out every 30 seconds. Defaults to 1.

WeedPauseDur (integer) (optional)
The number of seconds that a thread flushing a MultiPKFile pauses after updating cache entries in memory but before it begins atomically replacing volatile PKFiles and commiting the new stable MultiPKFile. Defaults to 0.

ReadImmutable (integer) (optional)
Controls whether the immutable parts of cache entries are read into memory when a MultiPKFile is flushed. If non-zero, the immutable fields are read into memory. If zero, the immutable parts of a cache entry are copied from the original MultiPKFile to the new one. Defaults to 0 (false).


The Vesta-2 configuration file (first check is in current directory).

The Vesta-2 configuration file (second check is in home directory).

The root of the sub-tree in which stable cache entry files (also known as MultiPKFiles) are stored. The files are stored under a pathname formed from their respective primary keys. See PrintMPKFile(1).

CacheLog files. The cache log contains new cache entries that have not yet been written to stable cache files. See PrintCacheLog(1).

GraphLog files. The graph log records elements of the cache entry graph for use by the Vesta-2 weeder. See PrintGraphLog(1).

Cache entry index (CI) files. The CI-log records which cache entry indices are in use.

Weeded MPKFile log files. This log records a prefix of the $MPKsToWeed variable (below) corresponding to those MultiPKFiles that have been successfully weeded.

Records the current state of the function cache's deleting stable variable.

Records the current state of the function cache's hit-filter stable variable.

Records the current state of the function cache's mpksToWeed stable variable. This records the list of MultiPKFiles that need weeding, and is only relevant if deleting is true.


The function cache crashes occasionally due to a memory smash we have not tracked down. A common symptom of the crash is the following assertion failure:

Assertion failed: logNode->kind == GraphLog::NodeKind, file CacheS.C, line 2003
However, the bug is not terribly serious because the function cache recovers just fine when it is restarted.

See the VCacheToDo(7) man page for a complete list of things that remain to be done to complete the cache server implementation.

See Also

CleanCache(1), ChkptCache(1), CreateCacheDirs(1), EraseCache(1), FlushCache(1), PrintCacheLog(1), PrintCacheVal(1), PrintGraphLog(1), PrintMPKFile(1), ShowCache(1), VCacheMonitor(1), VCacheStats(1), VestaWeed(1), WhichCache(1), MultiPKFile(5), VCacheImpl(7), VCacheLocks(7), VCacheSources(7), VCacheToDo(7)


Allan Heydon (

This page was generated automatically by mtex software.