Java Doc for FastMap.java in  » Development » Javolution » javolution » util » Java Source Code / Java DocumentationJava Source Code and Java Documentation

This class represents a hash map with real-time behavior; smooth capacity increase and thread-safe without external synchronization when FastMap.isShared shared .

FastMap has a predictable iteration order, which is the order in which keys are inserted into the map (similar to java.util.LinkedHashMap collection class). If the map is marked FastMap.setShared(boolean) shared then all operations are thread-safe including iterations over the map's collections. Unlike ConcurrentHashMap, FastMap.get(Object) access never blocks; retrieval reflects the map state not older than the last time the accessing threads have been synchronized (for multi-processors systems synchronizing ensures that the CPU internal cache is not stale).

FastMap may use custom key comparators; the default comparator is either FastComparator.DIRECT DIRECT or FastComparator.REHASH REHASH based upon the current Javolution Configuration. Users may explicitly set the key comparator to FastComparator.DIRECT DIRECT for optimum performance when the hash codes are well distributed for all run-time platforms (e.g. calculated hash codes).

Custom key comparators are extremely useful for value retrieval when map's keys and argument keys are not of the same class (such as String and javolution.text.Text Text ( FastComparator.LEXICAL LEXICAL )), to substitute more efficient hash code calculations ( FastComparator.STRING STRING ) or for identity maps ( FastComparator.IDENTITY IDENTITY ):[code] FastMap identityMap = new FastMap().setKeyComparator(FastComparator.IDENTITY); [/code]

FastMap.Entry can quickly be iterated over (forward or backward) without using iterators. For example:[code] FastMap map = ...; for (FastMap.Entry e = map.head(), end = map.tail(); (e = e.getNext()) != end;) { String key = e.getKey(); // No typecast necessary. Thread value = e.getValue(); // No typecast necessary. }[/code]

Custom map implementations may override the FastMap.newEntry method in order to return their own Entry implementation (with additional fields for example).

FastMap are Reusable reusable ; they maintain an internal pool of Map.Entry objects. When an entry is removed from a map, it is automatically restored to its pool (unless the map is shared in which case the removed entry is candidate for garbage collection as it cannot be safely recycled).

Shared maps do not use internal synchronization, except in case of concurrent modifications of the map structure (entry added/deleted). Reads and iterations are never synchronized and never blocking. With regards to the memory model, shared maps are equivalent to shared non-volatile variables (no "happen before" guarantee). There are typically used as lookup tables. For example:[code] public class Unit { static FastMap labels = new FastMap().setShared(true); ... public String toString() { String label = labels.get(this); // No synchronization. return label != null ? label : makeLabel(); } }[/code]

Implementation Note: To maintain time-determinism, rehash/resize is performed only when the map's size is small (see chart). For large maps (size > 512), the collection is divided recursively into (64) smaller sub-maps. The cost of the dispatching (based upon hashcode value) has been measured to be at most 20% of the access time (and most often way less).

Sets the shared status of this map (whether the map is thread-safe or not).

Note: Shared maps in ImmortalMemory (e.g. static) should not remove their entries as it could cause a memory leak (ImmortalMemory is never garbage collected), instead they should set their entry values to null.

Note: Shared maps in ImmortalMemory (e.g. static) should not remove their entries as it could cause a memory leak (ImmortalMemory is never garbage collected), instead they should set their entry values to null.

Sets the shared status of this map (whether the map is thread-safe or not). Shared maps are typically used for lookup table (e.g. static instances in ImmortalMemory). They support concurrent access (e.g. iterations) without synchronization, the maps updates themselves are synchronized internally.

Unlike ConcurrentHashMap access to a shared map never blocks. Retrieval reflects the map state not older than the last time the accessing thread has been synchronized (for multi-processors systems synchronizing ensures that the CPU internal cache is not stale).

Note: If concurrent updates are performed, application should not rely upon the size during iterations.