sofya.graphs
Class GraphCache

java.lang.Object
  sofya.graphs.GraphCache

Direct Known Subclasses:

CFGCache

public abstract class GraphCache
extends java.lang.Object

Abstract base implementation of a disk backed soft memory cache for graphs produced by the Sofya system.

A least recently used (LRU) policy is used to move graphs from memory to disk files when a minimum free memory threshold is crossed. It is the responsibility of subclasses to implement the methods responsible for actually serializing graphs of a particular type to file.

Version:

03/09/2005

Author:

Alex Kinneer

Nested Class Summary

static class

GraphCache.CachedGraph Container class used to encapsulate a cached graph and its associated status for passing to external users of the cache.

Constructor Summary

GraphCache()
Creates a new graph cache with a default minimum memory threshold and disk caching policy.

GraphCache(int initRemoveNum)
Creates a new graph cache with a default minimum memory threshold which immediately caches a given number of graphs to disk when the threshold is passed.

GraphCache(int initRemoveNum, float lowMemThreshold)
Creates a new graph cache which immediately caches the specified number of graphs when the given minimum memory threshold is passed.

Method Summary

void	clear() Clears the cache.
boolean	containsKey(MethodSignature method) Reports whether the cache contains a mapping for a given key.
GraphCache.CachedGraph	get(MethodSignature method) Gets a graph from the cache.
java.util.Collection	getForClass(java.lang.String className) Gets all of the graphs in the cache for a given class.
java.util.Iterator	iterator() Gets an iterator over the graphs in the cache.
java.util.Iterator	iterator(java.lang.String className) Gets an iterator over the graphs in the cache which are associated with a specified class.
java.util.Set	keySet() Gets the key set for the cache, in no particular order.
java.util.Set	keySet(java.lang.String className) Gets the key set consisting of the keys for all graphs in the cache associated with a particular class, in no particular order.
GraphCache.CachedGraph	put(MethodSignature method, Graph g) Adds a new graph to the cache.
protected abstract Graph	readFromDisk(MethodSignature method) Reads a graph from a disk cache file.
boolean	remove(MethodSignature method) Removes a graph from the cache.
int	size() Gets the number of graphs currently in the cache.
java.util.Iterator	sortedIterator() Gets a sorted iterator over the graphs in the cache.
java.util.Iterator	sortedIterator(java.lang.String className) Gets a sorted iterator over the graphs in the cache which are associated with a specified class.
protected abstract void	writeToDisk(MethodSignature method, Graph g) Writes a graph to a disk cache file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GraphCache

public GraphCache()

Creates a new graph cache with a default minimum memory threshold and disk caching policy.

GraphCache

public GraphCache(int initRemoveNum)

Creates a new graph cache with a default minimum memory threshold which immediately caches a given number of graphs to disk when the threshold is passed.

Parameters:

initRemoveNum - Number of graphs to immediately cache to disk when available memory falls below the minimum threshold. Higher values may improve performance by immediately clearing more memory and thus reducing the frequency with which the cache must search for and cache eligible graphs.

GraphCache

public GraphCache(int initRemoveNum,
                  float lowMemThreshold)

Creates a new graph cache which immediately caches the specified number of graphs when the given minimum memory threshold is passed.

Parameters:

initRemoveNum - Number of graphs to immediately cache to disk when available memory falls below the minimum threshold. Higher values may improve performance by immediately clearing more memory and thus reducing the frequency with which the cache must search for and cache eligible graphs.

lowMemThreshold - Minimum free memory, as a percentage of total memory, that the cache must attempt to keep free. Setting this value too high may result in disk thrashing.

Method Detail

put

public GraphCache.CachedGraph put(MethodSignature method,
                                  Graph g)
                           throws CacheException

Adds a new graph to the cache.

This action may result in existing graphs being cached to disk, if the addition of the new graph causes free memory to drop below the minimum threshold.

Parameters:

method - Signature of the method for which a graph is being cached, used as the key to retrieve the graph later.

g - Graph being added to the cache.

Returns:

A GraphCache.CachedGraph which can be used to modify the publicly visible status of the graph. The graph itself cannot be accessed through this object (GraphCache.CachedGraph.getGraph() will return null) since the existence of a strong reference would prevent it from being removed from memory. The get(sofya.base.MethodSignature) method should be used instead to retrieve the graph.

Throws:

CacheException - If the operation results in an attempt to cache graphs to disk, and that operation fails for any reason.

get

public GraphCache.CachedGraph get(MethodSignature method)
                           throws CacheException

Gets a graph from the cache.

The graph will be read from disk, if necessary. This method may also result in graphs being cached to disk, if the retrieval of the current graph causes free memory to fall below the minimum threshold.

Parameters:

method - Signature of the method for which to retrieve a graph.

Returns:

A GraphCache.CachedGraph which may be used to access the graph and modify the publicly visible status of the graph.

Throws:

CacheException - If no graph exists in the cache for the requested method, or if the graph must be read from a cache file and that operation fails for any reason.

remove

public boolean remove(MethodSignature method)

Removes a graph from the cache.

Parameters:

method - Signature of the method for which the graph is to be removed.

Returns:

true if a graph was found for the method and successfully removed, false otherwise.

clear

public void clear()

Clears the cache.

size

public int size()

Gets the number of graphs currently in the cache.

Returns:

The number of graphs currently cached.

getForClass

public java.util.Collection getForClass(java.lang.String className)

Gets all of the graphs in the cache for a given class.

Parameters:

className - Name of the class for which to retrieve all of its graphs.

Returns:

A collection containing all of the graphs found in the cache which are associated with the specified class.

Throws:

java.lang.OutOfMemoryError - If there is not enough space in memory to hold all of the graphs. For this reason, it is recommended that graphs instead be retrieved using either a direct iterator or by iterating over the key set.

keySet

public java.util.Set keySet()

Gets the key set for the cache, in no particular order.

Returns:

The set of keys to graphs in the cache, in no guaranteed order.

keySet

public java.util.Set keySet(java.lang.String className)
                     throws CacheException

Gets the key set consisting of the keys for all graphs in the cache associated with a particular class, in no particular order.

Parameters:

className - Name of the class for which the keys of associated graphs are to be retrieved.

Returns:

The set of keys to graphs in the cache which are associated with the specified class, in no guaranteed order.

Throws:

CacheException - If no graphs associated with the given class are found in the cache.

containsKey

public boolean containsKey(MethodSignature method)

Reports whether the cache contains a mapping for a given key.

Parameters:

method - Method signature which is the key for which to check if a mapping exists in the cache.

Returns:

true if the cache contains a mapping for the given key, false otherwise.

iterator

public java.util.Iterator iterator()

Gets an iterator over the graphs in the cache.

Returns:

An iterator over the graphs in the cache. The iterator makes no guarantee regarding the order of iteration.

sortedIterator

public java.util.Iterator sortedIterator()

Gets a sorted iterator over the graphs in the cache.

The order of iteration is consistent with the lexical ordering of the names of the methods with which the graphs are associated.

Returns:

An iterator over the graphs in the cache, which iterates over the graphs in the order determined by a lexical sorting of the names of the methods with which the graphs are associated.

See Also:

MethodSignature.NameComparator

iterator

public java.util.Iterator iterator(java.lang.String className)
                            throws CacheException

Gets an iterator over the graphs in the cache which are associated with a specified class.

Parameters:

className - Name of the class with which the graphs returned by the iterator should be associated.

Returns:

An iterator over the graphs in the cache which are associated with the specified class. The iterator makes no guarantee regarding the order of iteration.

Throws:

CacheException

sortedIterator

public java.util.Iterator sortedIterator(java.lang.String className)
                                  throws CacheException

Gets a sorted iterator over the graphs in the cache which are associated with a specified class.

The order of iteration is consistent with the lexical ordering of the names of the methods with which the graphs are associated.

Parameters:

className - Name of the class with which the graphs returned by the iterator should be associated.

Returns:

An iterator over the graphs in the cache which are associated with the specified class, and which iterates over the graphs in the order determined by a lexical sorting of the names of the methods with which the graphs are associated.

Throws:

CacheException

See Also:

MethodSignature.NameComparator

readFromDisk

protected abstract Graph readFromDisk(MethodSignature method)
                               throws CacheException

Reads a graph from a disk cache file.

Parameters:

method - Signature of the method for which the graph is to be read back from a disk cache file.

Returns:

The graph for the given method which was read from the disk cache file.

Throws:

CacheException - If no disk cache file exists for the specified method, or if cache file is unreadable or invalid.

writeToDisk

protected abstract void writeToDisk(MethodSignature method,
                                    Graph g)
                             throws CacheException

Writes a graph to a disk cache file.

Parameters:

method - Signature of the method for which the graph is to be written to disk.

g - Graph which is to be written to disk.

Throws:

CacheException - If the cache file cannot be created, or if there is a problem writing the graph to the file.