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

java.lang.Object
  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