org.vrspace.neurogrid
Class SoftCache

java.lang.Object
  java.util.AbstractMap
      org.vrspace.neurogrid.SoftCache

All Implemented Interfaces:

java.util.Map

public class SoftCache

extends java.util.AbstractMap

MRU Memory-Sensitive SoftCache

This SoftCache implements storage in an MRU fashion. Every time an object is retrieved with get, that object is put at the head of the MRU list. In the constructor, SoftCache, the maximum size of the MRU list can be specified. Any item that has been #put{Object,Object put} which is not on the MRU list is susceptible to being garbage collected. All values in this Map are stored via SoftReferences. Objects that are only softly reachable are eligible for reclamation by the garbage collector when there are only soft references to them. In this context, this would mean there is no thread which could follow a chain of references to get to the object - the only reference to the object is within this map. The garbage collector is required to clear all soft references before throwing an OutOfMemoryError.

Author:

josip,btscully Change History
------------------------------------------------------------------------------------
0.0 8/March/2001 josip Created file
0.1 8/November/2002 btscully Added functionality to clean out keys with cleared values Added functionality to maintain N MRU "hard" refs Implements Map Implementation borrowed from DevX http://archive.devx.com/java/free/articles/Kabutz01/Kabutz01-1.asp archive 0.11 8/November/2002 btscully Fixed NPEs from uninitialized ReferenceQueue and unchecked remove() method 0.2 8/November/2002 btscully Fixed null key in SoftValue causing unexpected behavior Added functionality to perform a memory-sensitive callback OutOfMemoryErrors thrown will cause the MRU SoftCache to shrink in exponentially decaying fashion If OOMEs continue to be thrown after MRU is empty, these are rethrown 0.21 8/November/2002 btscully Removed leftover debug statement when get is performed and value is already released 0.22 9/November/2002 btscully Added documentation; deprecated methods and attributes soon to disappear 0.3 13/November/2002 btscully Changed MRU implementation into a LinkedHashMap; reverted mruSize to Integer (4 bytes should be enough) 0.31 13/November/2002 btscully Fixed a couple bugs with iterators in memorySensitiveCallback - this code block still needs work.

Nested Class Summary

class	SoftCache.MRUMap
protected class	SoftCache.SoftValue Internal class to allow for easy removal of key-value pair when value has been reclaimed from SoftReference

Nested classes inherited from class java.util.Map

java.util.Map.Entry

Constructor Summary

SoftCache()
Default constructor instantiates SoftCache with a default size of 100 items

SoftCache(int mruSize)
Constructor allowing for parameterization of mru size.

Method Summary

void	clear() Clears SoftCache, MRU list.
java.util.Set	entrySet() Throws an UnsupportedOperationException
java.lang.Object	get(java.lang.Object key) Retreives an object from the SoftCache.
boolean	memorySensitiveCallback(java.lang.reflect.Method callback, java.lang.Object target, java.lang.Object[] args) Executes method callback on Object target with arguments args.
protected void	processQueue() Removes keys for SoftReferences that have been enqueued.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Stores an object to the SoftCache.
java.lang.Object	remove(java.lang.Object key) Removes an object from the SoftCache.
int	size() Returns size of SoftCache.

Methods inherited from class java.util.AbstractMap

clone, containsKey, containsValue, equals, hashCode, isEmpty, keySet, putAll, toString, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SoftCache

public SoftCache()

Default constructor instantiates SoftCache with a default size of 100 items

SoftCache

public SoftCache(int mruSize)

Constructor allowing for parameterization of mru size.

Method Detail

get

public java.lang.Object get(java.lang.Object key)

Retreives an object from the SoftCache. If there is a value that corresponds to the key it is returned and that key is placed at the head of the MRU list. If the key points to a value that has been reclaimed by the garbage collector, that key is removed from the backing Map.

Parameters:

key -

Returns:

Object

processQueue

protected void processQueue()

Removes keys for SoftReferences that have been enqueued. Altered from DevX version for clarity

Returns:

void

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Stores an object to the SoftCache. Before storing the value, the SoftCache takes the opportunity to clear any SoftReferences that have been enqueued.

Parameters:

key -

value -

Returns:

Object

memorySensitiveCallback

public boolean memorySensitiveCallback(java.lang.reflect.Method callback,
                                       java.lang.Object target,
                                       java.lang.Object[] args)

Executes method callback on Object target with arguments args. If that method throws an OutOfMemoryError, the oldest half of the MRU SoftCache is dumped - allowing for these entries to be garbage collected. The method is then invoked again, and this proceeds in a recursive fashion - for example if the method throws an OutOfMemoryError after half of the MRU SoftCache has been dropped, half of the remaining MRU SoftCache is dropped. When the MRU SoftCache is emptied, the OutOfMemoryError is thrown back up the call stack to the original caller of this method. What is being considered is to make this a static method that operates on all of the instances of SoftCache at the same time.

Parameters:

callback -

target -

args -

Returns:

boolean

remove

public java.lang.Object remove(java.lang.Object key)

Removes an object from the SoftCache. If the object exists in the SoftCache, its SoftReference is checked to see if the value has been reclaimed. If it has not been reclaimed, the value is returned - otherwise, null is returned. It is not a problem if this value is in the MRU list, since this value will eventually drop off the list.

Parameters:

key -

Returns:

Object

size

public int size()

Returns size of SoftCache. The SoftCache takes this opportunity to release any enqueued SoftReferences.

Returns:

int

clear

public void clear()

Clears SoftCache, MRU list. The SoftCache takes this opportunity to release any enqueued SoftReferences.

Returns:

void

entrySet

public java.util.Set entrySet()

Throws an UnsupportedOperationException

Returns:

Set