org.terracotta.collections
Class ConcurrentDistributedMap<K,V>

java.lang.Object
  org.terracotta.collections.ConcurrentDistributedMap<K,V>

Type Parameters:

K - type of mapped keys

V - type of mapped values

All Implemented Interfaces:

ConcurrentMap<K,V>, Map<K,V>, LockableMap<K>

Direct Known Subclasses:

ConcurrentStringMap

public class ConcurrentDistributedMap<K,V>
extends Object
implements ConcurrentMap<K,V>, LockableMap<K>

A ConcurrentMap that automatically switches its implementation to one that is highly concurrent in a Terracotta DSO cluster. When Terracotta DSO isn't active, a traditional ConcurrentMap implementation like ConcurrentHashMap is used within a single JVM.

Map entries can't use null for keys or values.

One of the principal aspects of the Terracotta DSO optimized implementation is that locking is done on several levels.

First of all, each local instance of the map is always correctly synchronized locally to ensure consistency and coherency within a single JVM.

Secondly, cluster-wide locking is split up in two levels:

• Methods that operate on individual entries with identifiable keys will take fine-grained cluster-wide locks for each entry
• Other methods that operate on the entire map are locked with their own map-specific cluster-wide lock.

This cluster-wide locking scheme provides very high concurrency at the cost of unbalanced coherency. This means that the visibility of changes made through the key-based methods will not necessarily be in order with map-based locking methods and vice-versa.

Author:

Geert Bevin, Chris Dennis

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

ConcurrentDistributedMap()
Creates a new ConcurrentDistributedMap instance with a default lock type of WRITE and the default lock strategy of HashcodeLockStrategy.

ConcurrentDistributedMap(LockType lockType, LockStrategy<? super K> lockStrategy)
Creates a new ConcurrentDistributedMap instance that allows the specification of the internal lock type that should be used when Terracotta DSO is active.

ConcurrentDistributedMap(LockType lockType, LockStrategy<? super K> lockStrategy, int concurrency)
Creates a new ConcurrentDistributedMap instance that allows the specification of the internal lock type that should be used when Terracotta DSO is active and the concurrency of internal data structures.

Method Summary

void	__tc_applicator_clear()
void	__tc_applicator_put(Object obj, Object obj1)
void	__tc_applicator_remove(Object obj)
Collection	__tc_getAllEntriesSnapshot()
Collection	__tc_getAllLocalEntriesSnapshot()
void	__tc_put_logical(Object key, Object value)
void	__tc_remove_logical(Object key)
void	clear() This method clears the map locally on the node that is resides on but doesn't guarantee when this is done on other nodes in the cluster.
boolean	containsKey(Object key)
boolean	containsValue(Object value)
FinegrainedLock	createFinegrainedLock(K key) Obtain a fine-grained lock instance for a particular key.
Set<Map.Entry<K,V>>	entrySet()
boolean	flush(Object key, Object value)
V	get(Object key)
Collection<Map.Entry<K,V>>	getAllEntriesSnapshot()
Collection<Map.Entry<K,V>>	getAllLocalEntriesSnapshot()
List<Map<K,?>>	getConstituentMaps()
String	getLockIdForKey(K key)
Map.Entry<K,V>	getRandomEntry()
Map.Entry<K,V>	getRandomLocalEntry()
boolean	isEmpty() This method reflects the state of the map instance that is local on the node.
Set<K>	keySet()
int	localSize()
void	lockEntry(K key) In a shared instance of a concurrent distributed map this will lock the associated entry.
V	put(K key, V value)
void	putAll(Map<? extends K,? extends V> t)
V	putIfAbsent(K key, V value)
void	putNoReturn(K key, V value) Behaves the same as the standard put(Object, Object)���method except that the previous value is not returned.
MapSizeListener	registerMapSizeListener(MapSizeListener newListener)
V	remove(Object key)
boolean	remove(Object key, Object value)
void	removeNoReturn(K key) Behaves the same as the standard remove(Object) method except that the previous value is not returned.
V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
int	size() This method reflects the state of the map instance that is local on the node.
boolean	tryRemove(Object key, long time, TimeUnit unit)
V	unlockedGet(Object key)
void	unlockedPutNoReturn(K key, V value)
void	unlockedRemoveNoReturn(K key)
void	unlockEntry(K key) In a shared instance of a concurrent distributed map this will unlock the associated entry.
V	unsafeGet(K key) Perform a raw/unlocked read for the given key.
Collection<V>	values()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode

Constructor Detail

ConcurrentDistributedMap

public ConcurrentDistributedMap()

Creates a new ConcurrentDistributedMap instance with a default lock type of WRITE and the default lock strategy of HashcodeLockStrategy.

See Also:

ConcurrentDistributedMap(LockType, LockStrategy)

ConcurrentDistributedMap

public ConcurrentDistributedMap(LockType lockType,
                                LockStrategy<? super K> lockStrategy)

Creates a new ConcurrentDistributedMap instance that allows the specification of the internal lock type that should be used when Terracotta DSO is active.

Parameters:

lockType - the lock type that should be used internally when Terracotta DSO is active

lockStrategy - the lock strategy to use for this map

See Also:

LockType, LockStrategy

ConcurrentDistributedMap

public ConcurrentDistributedMap(LockType lockType,
                                LockStrategy<? super K> lockStrategy,
                                int concurrency)

Creates a new ConcurrentDistributedMap instance that allows the specification of the internal lock type that should be used when Terracotta DSO is active and the concurrency of internal data structures.

Parameters:

lockType - the lock type that should be used internally when Terracotta DSO is active

lockStrategy - the lock strategy to use for this map

concurrency - the estimated number of concurrently updating threads

See Also:

LockType, LockStrategy

Method Detail

putIfAbsent

public V putIfAbsent(K key,
                     V value)

Specified by:

putIfAbsent in interface ConcurrentMap<K,V>

remove

public boolean remove(Object key,
                      Object value)

Specified by:

remove in interface ConcurrentMap<K,V>

replace

public V replace(K key,
                 V value)

Specified by:

replace in interface ConcurrentMap<K,V>

removeNoReturn

public void removeNoReturn(K key)

Behaves the same as the standard remove(Object) method except that the previous value is not returned. This can provide significant performance improvements when used in a Terracotta DSO cluster.

Parameters:

key - the key of the entry to remove

unlockedRemoveNoReturn

public void unlockedRemoveNoReturn(K key)

replace

public boolean replace(K key,
                       V oldValue,
                       V newValue)

Specified by:

replace in interface ConcurrentMap<K,V>

clear

public void clear()

This method clears the map locally on the node that is resides on but doesn't guarantee when this is done on other nodes in the cluster. It is possible that methods that operate on specific keys are actually reordered and execute in unexpected ways across the cluster.

Specified by:

clear in interface Map<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

unsafeGet

public V unsafeGet(K key)

Perform a raw/unlocked read for the given key. It performs no locking and thus provides absolutely no visibility semantics. If the value is not local it will NOT be faulted and null is returned instead -- thus one cannot distinguish between a non-existent mapping from an un-faulted value. USE WITH CAUTION

Parameters:

key - The key to lookup

Returns:

A value mapped to the given key (but not necessarily the most current) value or null if the value is missing or not local

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

entrySet

public Set<Map.Entry<K,V>> entrySet()

Specified by:

entrySet in interface Map<K,V>

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

unlockedGet

public V unlockedGet(Object key)

isEmpty

public boolean isEmpty()

This method reflects the state of the map instance that is local on the node. Any changes that are done through methods that operate on specific keys are not guaranteed to have been propagated throughout the cluster.

Specified by:

isEmpty in interface Map<K,V>

keySet

public Set<K> keySet()

Specified by:

keySet in interface Map<K,V>

put

public V put(K key,
             V value)

Specified by:

put in interface Map<K,V>

putNoReturn

public void putNoReturn(K key,
                        V value)

Behaves the same as the standard put(Object, Object)���method except that the previous value is not returned. This can provide significant performance improvements when used in a Terracotta DSO cluster.

Parameters:

key - the key of the entry to put

value - the value of the entry to put

unlockedPutNoReturn

public void unlockedPutNoReturn(K key,
                                V value)

putAll

public void putAll(Map<? extends K,? extends V> t)

Specified by:

putAll in interface Map<K,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

size

public int size()

This method reflects the state of the map instance that is local on the node. Any changes that are done through methods that operate on specific keys are not guaranteed to have been propagated throughout the cluster.

Specified by:

size in interface Map<K,V>

localSize

public int localSize()

values

public Collection<V> values()

Specified by:

values in interface Map<K,V>

getAllLocalEntriesSnapshot

public Collection<Map.Entry<K,V>> getAllLocalEntriesSnapshot()

getAllEntriesSnapshot

public Collection<Map.Entry<K,V>> getAllEntriesSnapshot()

createFinegrainedLock

public FinegrainedLock createFinegrainedLock(K key)

Description copied from interface: LockableMap

Obtain a fine-grained lock instance for a particular key.

Specified by:

createFinegrainedLock in interface LockableMap<K>

Parameters:

key - the key for which a fine-grained lock has to be constructed

Returns:

an instance of fine-grained lock that can be used to perform primitive locking operations on a key

lockEntry

public void lockEntry(K key)

In a shared instance of a concurrent distributed map this will lock the associated entry. In an unshared instance it is a no-op.

ConcurrentDistributedMap instances allow non existent entries to be locked.

Specified by:

lockEntry in interface LockableMap<K>

Parameters:

key - the key for which all entry accesses have to be locked

unlockEntry

public void unlockEntry(K key)

In a shared instance of a concurrent distributed map this will unlock the associated entry. In an unshared instance it is a no-op.

Specified by:

unlockEntry in interface LockableMap<K>

Parameters:

key - the key for which all entry accesses have to be unlocked

getLockIdForKey

public String getLockIdForKey(K key)

__tc_applicator_clear

public void __tc_applicator_clear()

__tc_applicator_put

public void __tc_applicator_put(Object obj,
                                Object obj1)

__tc_applicator_remove

public void __tc_applicator_remove(Object obj)

__tc_getAllEntriesSnapshot

public Collection __tc_getAllEntriesSnapshot()

__tc_getAllLocalEntriesSnapshot

public Collection __tc_getAllLocalEntriesSnapshot()

__tc_put_logical

public void __tc_put_logical(Object key,
                             Object value)

__tc_remove_logical

public void __tc_remove_logical(Object key)

getConstituentMaps

public List<Map<K,?>> getConstituentMaps()

getRandomEntry

public Map.Entry<K,V> getRandomEntry()

getRandomLocalEntry

public Map.Entry<K,V> getRandomLocalEntry()

flush

public boolean flush(Object key,
                     Object value)

tryRemove

public boolean tryRemove(Object key,
                         long time,
                         TimeUnit unit)

registerMapSizeListener

public MapSizeListener registerMapSizeListener(MapSizeListener newListener)