org.hd.d.efs
Class Utils.SimpleLRUMapAutoSizeForHitRate<K,V>

java.lang.Object
  extended by org.hd.d.efs.Utils.SimpleLRUMapAutoSizeForHitRate<K,V>
Enclosing class:
Utils

public static final class Utils.SimpleLRUMapAutoSizeForHitRate<K,V>
extends java.lang.Object

Simplified map with fixed capacity that discards excess items in LRU (Least Recently Used) order to meet a hit/miss ratio goal. This adjusts its size to maintain a specific hit/miss ratio in get(), a miss being a get() that returns null, trimming away older items at insert to maintain the ratio.

This will also discard entries LRU if memory is under stress while the map is above its minimum size.

This provides optional fixed lower and upper sizes. Attempts to insert more items than the ceiling capacity will result in old items being removed in LRU order, thus leaving the newest items in the cache.

Each put() or get() makes its key/value pair the most-recently used and thus the last to be removed from the map of current key/value pairs when a series of put()s forces the map to overflow.

Thread-safe.

A lock can be held on instances of this object to make compound operations atomic.

Does not support the full Map interface.


Field Summary
static float DEFAULT_LOAD_FACTOR
          Default load factor.
static float DEFAULT_MAX_MISS_RATE
          Default maximum miss rate ]0.0,1.0[.
static int DEFAULT_MIN_SIZE
          Default minimum size/capacity, also initial capacity; strictly positive.
 
Constructor Summary
Utils.SimpleLRUMapAutoSizeForHitRate()
          Create an instance with all defaults and therefore an effectively-unbounded upper capacity of Integer.MAX_VALUE.
Utils.SimpleLRUMapAutoSizeForHitRate(float maxMissRate, int minSize)
          Create an instance with the given parameters.
Utils.SimpleLRUMapAutoSizeForHitRate(float maxMissRate, int minSize, int maxCapacity, float loadFactor)
          Create an instance with the given parameters.
Utils.SimpleLRUMapAutoSizeForHitRate(int minSize, int maxCapacity)
          Create an instance with all defaults except for the specified minimum/maximum capacities.
 
Method Summary
 void clear()
          Clear the map and reset the hit/miss counters.
 void compact()
          Compact by discarding all LRU items above the minimum size, ignoring the miss-rate target.
static
<K,V> Utils.SimpleLRUMapAutoSizeForHitRate<K,V>
create(float maxMissRate, int minSize, int maxCapacity, float loadFactor)
          Create an instance with the given parameters.
 V get(K key)
          Get an entry from the map, making it the Most Recently Used; null if no such element.
 java.util.Map<K,V> getCopy()
          Take a copy of the map contents, which does not alter LRU; never null.
 V put(K key, V value)
          Put an entry in the map, making it the Most Recently Used, returning the previous value if any.
 V remove(K key)
          Remove an entry from the map and return the removed value, if any, else null.
 int size()
          Return the number of entries in the map; non-negative.
 java.lang.String toString()
          Provide a human-readable summary of status.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_MAX_MISS_RATE

public static final float DEFAULT_MAX_MISS_RATE
Default maximum miss rate ]0.0,1.0[.

See Also:
Constant Field Values

DEFAULT_LOAD_FACTOR

public static final float DEFAULT_LOAD_FACTOR
Default load factor.

See Also:
Constant Field Values

DEFAULT_MIN_SIZE

public static final int DEFAULT_MIN_SIZE
Default minimum size/capacity, also initial capacity; strictly positive.

See Also:
Constant Field Values
Constructor Detail

Utils.SimpleLRUMapAutoSizeForHitRate

public Utils.SimpleLRUMapAutoSizeForHitRate()
Create an instance with all defaults and therefore an effectively-unbounded upper capacity of Integer.MAX_VALUE.


Utils.SimpleLRUMapAutoSizeForHitRate

public Utils.SimpleLRUMapAutoSizeForHitRate(int minSize,
                                            int maxCapacity)
Create an instance with all defaults except for the specified minimum/maximum capacities.


Utils.SimpleLRUMapAutoSizeForHitRate

public Utils.SimpleLRUMapAutoSizeForHitRate(float maxMissRate,
                                            int minSize)
Create an instance with the given parameters. The standard default is used for the load factor, and the map size is effectively unlimited.

Parameters:
maxMissRate - the target cache maximum miss rate; in the range 0.0f to 1.0f exclusive (typically << 0.1)
minSize - the minimum (and initial) capacity; strictly positive

Utils.SimpleLRUMapAutoSizeForHitRate

public Utils.SimpleLRUMapAutoSizeForHitRate(float maxMissRate,
                                            int minSize,
                                            int maxCapacity,
                                            float loadFactor)
Create an instance with the given parameters.

Parameters:
maxMissRate - the target cache maximum miss rate; in the range 0.0f to 1.0f exclusive (typically << 0.1)
minSize - the minimum (and initial) capacity; strictly positive
maxCapacity - the maximum capacity; greater than minCapacity (and this strictly positive)
loadFactor - the load factor of the underlying hash table; in the range 0.0f to 1.0f exclusive (typically ~0.7f)
Method Detail

get

public V get(K key)
Get an entry from the map, making it the Most Recently Used; null if no such element.


create

public static <K,V> Utils.SimpleLRUMapAutoSizeForHitRate<K,V> create(float maxMissRate,
                                                                     int minSize,
                                                                     int maxCapacity,
                                                                     float loadFactor)
Create an instance with the given parameters.

Parameters:
maxMissRate - the target cache maximum miss rate; in the range 0.0f to 1.0f exclusive (typically << 0.1)
minSize - the minimum (and initial) capacity; strictly positive
maxCapacity - the maximum capacity; greater than minCapacity (and this strictly positive)
loadFactor - the load factor of the underlying hash table; in the range 0.0f to 1.0f exclusive (typically ~0.7f)

compact

public void compact()
Compact by discarding all LRU items above the minimum size, ignoring the miss-rate target. Excessive use may reduce the effectiveness of this map.

May be automatically called in the background when memory is low/stressed.


put

public V put(K key,
             V value)
Put an entry in the map, making it the Most Recently Used, returning the previous value if any.


remove

public V remove(K key)
Remove an entry from the map and return the removed value, if any, else null.


clear

public void clear()
Clear the map and reset the hit/miss counters.


size

public int size()
Return the number of entries in the map; non-negative.


getCopy

public java.util.Map<K,V> getCopy()
Take a copy of the map contents, which does not alter LRU; never null.


toString

public java.lang.String toString()
Provide a human-readable summary of status. Useful for debugging/tuning, for example.

Overrides:
toString in class java.lang.Object