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:

com.terracotta.toolkit.collections.InternalClusteredMap<K,V>, ConcurrentMap<K,V>, Map<K,V>, ClusteredMap<K,V>, MutatorsWithCallbacks<K,V>, LockableMap<K>

Direct Known Subclasses:

ConcurrentDistributedServerMap

public class ConcurrentDistributedMap<K,V>
extends Object
implements com.terracotta.toolkit.collections.InternalClusteredMap<K,V>, MutatorsWithCallbacks<K,V>

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>

Field Summary

protected CacheConfig	cacheConfig
static int	DEFAULT_CONCURRENCY
static boolean	DEFAULT_INVALIDATE_ON_CHANGE
protected boolean	deleteValueOnRemove
protected boolean	invalidateOnChange
protected ClusteredMap<K,V>	map
protected MutatorsWithCallbacks<K,V>	mutateCallbacks

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, GenericLockStrategy<L,? super K> lockStrategy, int concurrency)

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	checkInObject(K key, V value)
V	checkOutObject(K key, V value)
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.
void	clearWithCallback(MutationCallback<K,V> callback)
boolean	containsKey(Object key)
boolean	containsLocalKey(K key)
boolean	containsValue(Object value)
ClusteredLock	createFinegrainedLock(K key) Create a lock for the given key.
Set<Map.Entry<K,V>>	entrySet()
boolean	flush(Object key, Object value) Attempt to recover any local memory resources used by this mapping.
V	get(Object key)
Collection<Map.Entry<K,V>>	getAllEntriesSnapshot() A collection of all entries within this map.
Collection<Map.Entry<K,V>>	getAllLocalEntriesSnapshot() A collection of all in-heap entries within this map.
List<Map<K,V>>	getConstituentMaps() Get a list of the constituent maps that comprise this map.
Map.Entry<K,V>	getRandomEntry() Get a randomly selected entry from this map.
Map.Entry<K,V>	getRandomLocalEntry() Get a randomly selected in-heap entry from this map.
boolean	isEmpty() This method reflects the state of the map instance that is local on the node.
boolean	isPinned(K key)
Set<K>	keySet()
Set<K>	localKeySet()
int	localSize() Return the count of local in-heap entries.
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.
void	putNoReturnWithCallback(K key, V value, MutationCallback<K,V> callback)
MapSizeListener	registerMapSizeListener(MapSizeListener newListener) Register a map-size listener on this map.
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.
void	removeNoReturnWithCallback(K key, MutationCallback<K,V> callback)
V	removeWithCallback(K key, MutationCallback<K,V> callback)
boolean	removeWithCallback(K key, V value, MutationCallback<K,V> callback)
V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
void	setMaxTTI(int maxTTI)
void	setMaxTTL(int maxTTL)
void	setPinned(K key, boolean pinned)
void	setTargetMaxTotalCount(int targetMaxTotalCount)
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) Attempts to remove the mapping for the given key.
V	unlockedGet(Object key) Perform an unlocked read for the given key.
Map<K,V>	unlockedGetAll(Set<K> keys)
void	unlockedPutIfAbsentNoReturn(K key, V value)
void	unlockedPutIfAbsentNoReturnWithCallback(K key, V value, MutationCallback<K,V> callback)
void	unlockedPutNoReturn(K key, V value) Performs an unlocked ClusteredMap.putNoReturn(Object, Object)
void	unlockedPutNoReturnWithCallback(K key, V value, MutationCallback<K,V> callback)
void	unlockedRemoveNoReturn(K key) Performs an unlocked ClusteredMap.removeNoReturn(Object)
void	unlockedRemoveNoReturn(K key, V value)
void	unlockedRemoveNoReturnWithCallback(K key, MutationCallback<K,V> callback)
void	unlockedRemoveNoReturnWithCallback(K key, V value, MutationCallback<K,V> callback)
void	unlockedReplaceNoReturn(K key, V currentValue, V newValue)
void	unlockedReplaceNoReturnWithCallback(K key, V current, V newValue, MutationCallback<K,V> callback)
void	unlockEntry(K key) In a shared instance of a concurrent distributed map this will unlock the associated entry.
void	unpinAll()
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

Field Detail

DEFAULT_CONCURRENCY

public static final int DEFAULT_CONCURRENCY

See Also:

Constant Field Values

DEFAULT_INVALIDATE_ON_CHANGE

public static final boolean DEFAULT_INVALIDATE_ON_CHANGE

See Also:

Constant Field Values

map

protected final ClusteredMap<K,V> map

invalidateOnChange

protected final boolean invalidateOnChange

deleteValueOnRemove

protected final boolean deleteValueOnRemove

mutateCallbacks

protected final MutatorsWithCallbacks<K,V> mutateCallbacks

cacheConfig

protected final CacheConfig cacheConfig

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

ConcurrentDistributedMap

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

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>

removeWithCallback

public boolean removeWithCallback(K key,
                                  V value,
                                  MutationCallback<K,V> callback)

Specified by:

removeWithCallback in interface MutatorsWithCallbacks<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.

Specified by:

removeNoReturn in interface ClusteredMap<K,V>

Parameters:

key - the key of the entry to remove

unlockedRemoveNoReturn

public void unlockedRemoveNoReturn(K key)

Description copied from interface: ClusteredMap

Performs an unlocked ClusteredMap.removeNoReturn(Object)

Specified by:

unlockedRemoveNoReturn in interface ClusteredMap<K,V>

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

Specified by:

unsafeGet in interface ClusteredMap<K,V>

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)

Description copied from interface: ClusteredMap

Perform an unlocked read for the given key.

This method performs no locking and thus provides no visibility guarantees.

Specified by:

unlockedGet in interface ClusteredMap<K,V>

Parameters:

key - the key to lookup

Returns:

a value mapped to the given key (but not necessarily the current mapping)

unlockedGetAll

public Map<K,V> unlockedGetAll(Set<K> keys)

Specified by:

unlockedGetAll in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

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>

localKeySet

public Set<K> localKeySet()

Specified by:

localKeySet in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

unpinAll

public void unpinAll()

Specified by:

unpinAll in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

isPinned

public boolean isPinned(K key)

Specified by:

isPinned in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

setPinned

public void setPinned(K key,
                      boolean pinned)

Specified by:

setPinned in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

containsLocalKey

public boolean containsLocalKey(K key)

Specified by:

containsLocalKey in interface com.terracotta.toolkit.collections.InternalClusteredMap<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.

Specified by:

putNoReturn in interface ClusteredMap<K,V>

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)

Description copied from interface: ClusteredMap

Performs an unlocked ClusteredMap.putNoReturn(Object, Object)

Specified by:

unlockedPutNoReturn in interface ClusteredMap<K,V>

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()

Description copied from interface: ClusteredMap

Return the count of local in-heap entries.

Specified by:

localSize in interface ClusteredMap<K,V>

Returns:

count of local entries

values

public Collection<V> values()

Specified by:

values in interface Map<K,V>

getAllLocalEntriesSnapshot

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

Description copied from interface: ClusteredMap

A collection of all in-heap entries within this map.

Specified by:

getAllLocalEntriesSnapshot in interface ClusteredMap<K,V>

Returns:

all in-heap map entries

getAllEntriesSnapshot

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

Description copied from interface: ClusteredMap

A collection of all entries within this map.

Specified by:

getAllEntriesSnapshot in interface ClusteredMap<K,V>

Returns:

all map entries

createFinegrainedLock

public ClusteredLock createFinegrainedLock(K key)

Description copied from interface: ClusteredMap

Create a lock for the given key.

This methods returns as finegrained a lock that still provides exclusion against modification of the mapping for this key.

Specified by:

createFinegrainedLock in interface ClusteredMap<K,V>

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

__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,V>> getConstituentMaps()

Description copied from interface: ClusteredMap

Get a list of the constituent maps that comprise this map.

This list will be a singleton list whose element is this if this map is not a composite map.

Specified by:

getConstituentMaps in interface ClusteredMap<K,V>

Returns:

the constituent maps

getRandomEntry

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

Description copied from interface: ClusteredMap

Get a randomly selected entry from this map.

Specified by:

getRandomEntry in interface ClusteredMap<K,V>

Returns:

a random map entry

getRandomLocalEntry

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

Description copied from interface: ClusteredMap

Get a randomly selected in-heap entry from this map.

Specified by:

getRandomLocalEntry in interface ClusteredMap<K,V>

Returns:

a random in-heap entry

flush

public boolean flush(Object key,
                     Object value)

Description copied from interface: ClusteredMap

Attempt to recover any local memory resources used by this mapping.

Specified by:

flush in interface ClusteredMap<K,V>

Parameters:

key - key for the mapping

value - value for the mapping

Returns:

true if memory was recovered

tryRemove

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

Description copied from interface: ClusteredMap

Attempts to remove the mapping for the given key.

If the mapping is succesfully removed inside the specified time then true is returned.

Specified by:

tryRemove in interface ClusteredMap<K,V>

Parameters:

key - key for the mapping to be removed

time - time to spend attempting removal

unit - time unit for the timeout

Returns:

true if the mapping was removed

registerMapSizeListener

public MapSizeListener registerMapSizeListener(MapSizeListener newListener)

Description copied from interface: ClusteredMap

Register a map-size listener on this map.

This method returns the listener previously associated with this map. This allows for simple listener chaining or composition when multiple listeners are required. If no listener was previously registered then null is returned.

Specified by:

registerMapSizeListener in interface ClusteredMap<K,V>

Parameters:

newListener - listener to register

Returns:

the previous listener

putNoReturnWithCallback

public void putNoReturnWithCallback(K key,
                                    V value,
                                    MutationCallback<K,V> callback)

Specified by:

putNoReturnWithCallback in interface MutatorsWithCallbacks<K,V>

clearWithCallback

public void clearWithCallback(MutationCallback<K,V> callback)

Specified by:

clearWithCallback in interface MutatorsWithCallbacks<K,V>

removeNoReturnWithCallback

public void removeNoReturnWithCallback(K key,
                                       MutationCallback<K,V> callback)

Specified by:

removeNoReturnWithCallback in interface MutatorsWithCallbacks<K,V>

removeWithCallback

public V removeWithCallback(K key,
                            MutationCallback<K,V> callback)

Specified by:

removeWithCallback in interface MutatorsWithCallbacks<K,V>

unlockedPutNoReturnWithCallback

public void unlockedPutNoReturnWithCallback(K key,
                                            V value,
                                            MutationCallback<K,V> callback)

Specified by:

unlockedPutNoReturnWithCallback in interface MutatorsWithCallbacks<K,V>

unlockedRemoveNoReturnWithCallback

public void unlockedRemoveNoReturnWithCallback(K key,
                                               MutationCallback<K,V> callback)

Specified by:

unlockedRemoveNoReturnWithCallback in interface MutatorsWithCallbacks<K,V>

unlockedReplaceNoReturn

public void unlockedReplaceNoReturn(K key,
                                    V currentValue,
                                    V newValue)

Specified by:

unlockedReplaceNoReturn in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

unlockedRemoveNoReturn

public void unlockedRemoveNoReturn(K key,
                                   V value)

Specified by:

unlockedRemoveNoReturn in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

unlockedPutIfAbsentNoReturn

public void unlockedPutIfAbsentNoReturn(K key,
                                        V value)

Specified by:

unlockedPutIfAbsentNoReturn in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

unlockedRemoveNoReturnWithCallback

public void unlockedRemoveNoReturnWithCallback(K key,
                                               V value,
                                               MutationCallback<K,V> callback)

Specified by:

unlockedRemoveNoReturnWithCallback in interface MutatorsWithCallbacks<K,V>

unlockedReplaceNoReturnWithCallback

public void unlockedReplaceNoReturnWithCallback(K key,
                                                V current,
                                                V newValue,
                                                MutationCallback<K,V> callback)

Specified by:

unlockedReplaceNoReturnWithCallback in interface MutatorsWithCallbacks<K,V>

unlockedPutIfAbsentNoReturnWithCallback

public void unlockedPutIfAbsentNoReturnWithCallback(K key,
                                                    V value,
                                                    MutationCallback<K,V> callback)

Specified by:

unlockedPutIfAbsentNoReturnWithCallback in interface MutatorsWithCallbacks<K,V>

setTargetMaxTotalCount

public void setTargetMaxTotalCount(int targetMaxTotalCount)

Specified by:

setTargetMaxTotalCount in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

setMaxTTI

public void setMaxTTI(int maxTTI)

Specified by:

setMaxTTI in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

setMaxTTL

public void setMaxTTL(int maxTTL)

Specified by:

setMaxTTL in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

checkInObject

public void checkInObject(K key,
                          V value)

Specified by:

checkInObject in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>

checkOutObject

public V checkOutObject(K key,
                        V value)

Specified by:

checkOutObject in interface com.terracotta.toolkit.collections.InternalClusteredMap<K,V>