Documentation for package rsm.cache

Author : R. Scott McIntire

Version: 1.1

Overview:

Provides a class that caches a limited number of numerically ranked objects.
The constructor make-standard-cache creates a cache and the method 
cache-if-large is used to cache objects of large rank.

REQUIRES: package rsm.queue.

Export Summary:

make-standard-cache: Create an instance of a cache.
cache-if-large     : Cache an object if it is large than the current values in 
                     the cache.
cache-min-value    : Find the minimum value of the cache.

clear-and-set-obj-cache-size: Clear the cache and set its size.

retrieve-obj-cache : Retrieve the cache as a list. Each element of the 
                     list has the form (value (list-of-objs)).

cache-if-large   (cache obj value &key (test #'equal))

Place an object in the cache if either a or b below is true:

a). The internal cache threshold is nil.
b). The value of the object to cache is larger than the internal 
    cache threshold. 

AND 

if either 1, 2, or 3 below is true:

1). The cache is not full.
2). The cache is full AND the rank of the object is larger than the minimum rank
    of the cache.
3). The cache is full AND the rank of an object is the same as a list of objects
    in the cache AND the object is considered to be different than any of the
    elements in this list. The keyword <test> will be used to determine if an
    element is considered different. If the slot cache-list-limit of <cache> is
    specified, the lists of equal valued objects will be limited to length,
    cache-list-limit. Otherwise, the cache lists will have no limit.

cache-min-value   (cache)

Find the minimum of the values in the cache.

clear-and-set-obj-cache-size   (cache n)

Clear the object <cache> and set the new size to <n>.

make-standard-cache   (name cache-size &key (threshold nil) (cache-list-limit nil))

Create an instance of class standard-cache. The cache will have name, <name>;
and cache size, <cache-size>. If <threshold> is non-nil, then no value will 
be stored in the cache if less than <threshold>. If placed in the cache, 
an object will be added to a list of other objects of equal numerical rank.
If <cache-list-limit> is non-nil, limit the list length of equally ranked 
objects to <cache-list-limit>. Otherwise, there will be no limit the 
lists of equal rank.

retrieve-obj-cache   (cache)

Retrieve a list of the form, (value (list-of-objs)), from <cache> 
ordered from highest to lowest value. The list represents the "k" best 
solutions in the sense that each element of the list returned is a pairing 
of a fit value and a corresponding list of objects with that value.