Class PrivateMaxEntriesMap<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

tools.jackson.databind.util.internal.PrivateMaxEntriesMap<K,V>

Type Parameters:

K - the type of keys maintained by this map

V - the type of mapped values

All Implemented Interfaces:

Serializable, ConcurrentMap<K,V>, Map<K,V>

public final class PrivateMaxEntriesMap<K,V>
extends AbstractMap<K,V>
implements ConcurrentMap<K,V>, Serializable

A hash table supporting full concurrency of retrievals, adjustable expected concurrency for updates, and a maximum capacity to bound the map by. This implementation differs from ConcurrentHashMap in that it maintains a page replacement algorithm that is used to evict an entry when the map has exceeded its capacity. Unlike the Java Collections Framework, this map does not have a publicly visible constructor and instances are created through a PrivateMaxEntriesMap.Builder.

An entry is evicted from the map when the entry size exceeds its maximum capacity threshold.

An EvictionListener may be supplied for notification when an entry is evicted from the map. This listener is invoked on a caller's thread and will not block other threads from operating on the map. An implementation should be aware that the caller's thread will not expect long execution times or failures as a side effect of the listener being notified. Execution safety and a fast turn around time can be achieved by performing the operation asynchronously, such as by submitting a task to an ExecutorService.

The concurrency level determines the number of threads that can concurrently modify the table. Using a significantly higher or lower value than needed can waste space or lead to thread contention, but an estimate within an order of magnitude of the ideal value does not usually have a noticeable impact. Because placement in hash tables is essentially random, the actual concurrency will vary.

This class and its views and iterators implement all of the optional methods of the Map and Iterator interfaces.

Like Hashtable but unlike HashMap, this class does not allow null to be used as a key or value. Unlike LinkedHashMap, this class does not provide predictable iteration order. A snapshot of the keys and entries may be obtained in ascending and descending order of retention.

See Also:

• http://code.google.com/p/concurrentlinkedhashmap/
• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) final class	PrivateMaxEntriesMap.AddTask	Adds the node to the page replacement policy.
static final class	PrivateMaxEntriesMap.Builder<K,V>	A builder that creates PrivateMaxEntriesMap instances.
(package private) static enum	PrivateMaxEntriesMap.DrainStatus	The draining status of the buffers.
(package private) final class	PrivateMaxEntriesMap.EntryIterator	An adapter to safely externalize the entry iterator.
(package private) final class	PrivateMaxEntriesMap.EntrySet	An adapter to safely externalize the entries.
(package private) final class	PrivateMaxEntriesMap.KeyIterator	An adapter to safely externalize the key iterator.
(package private) final class	PrivateMaxEntriesMap.KeySet	An adapter to safely externalize the keys.
(package private) static final class	PrivateMaxEntriesMap.Node<K,V>	A node contains the key, the weighted value, and the linkage pointers on the page-replacement algorithm's data structures.
(package private) final class	PrivateMaxEntriesMap.RemovalTask	Removes a node from the page replacement policy.
(package private) static final class	PrivateMaxEntriesMap.SerializationProxy<K,V>	A proxy that is serialized instead of the map.
(package private) final class	PrivateMaxEntriesMap.UpdateTask	Updates the weighted size and evicts an entry on overflow.
(package private) final class	PrivateMaxEntriesMap.ValueIterator	An adapter to safely externalize the value iterator.
(package private) final class	PrivateMaxEntriesMap.Values	An adapter to safely externalize the values.
(package private) static final class	PrivateMaxEntriesMap.WeightedValue<V>	A value, its weight, and the entry's status.
(package private) final class	PrivateMaxEntriesMap.WriteThroughEntry	An entry that allows updates to write through to the map.

Nested classes/interfaces inherited from class AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface Map

Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field	Description
(package private) final AtomicLong	capacity
(package private) final int	concurrencyLevel
(package private) final ConcurrentMap<K, PrivateMaxEntriesMap.Node<K,V>>	data
(package private) final AtomicReference<PrivateMaxEntriesMap.DrainStatus>	drainStatus
(package private) Set<Map.Entry<K,V>>	entrySet
(package private) final LinkedDeque<PrivateMaxEntriesMap.Node<K,V>>	evictionDeque
(package private) final Lock	evictionLock
(package private) Set<K>	keySet
(package private) static final long	MAXIMUM_CAPACITY	The maximum capacity of the map.
(package private) static final int	NCPU	The number of CPUs
(package private) static final int	NUMBER_OF_READ_BUFFERS	The number of read buffers to use.
(package private) static final int	READ_BUFFER_DRAIN_THRESHOLD	The maximum number of read operations to perform per amortized drain.
(package private) static final int	READ_BUFFER_INDEX_MASK	Mask value for indexing into the read buffer.
(package private) static final int	READ_BUFFER_SIZE	The maximum number of pending reads per buffer.
(package private) static final int	READ_BUFFER_THRESHOLD	The number of pending read operations before attempting to drain.
(package private) static final int	READ_BUFFERS_MASK	Mask value for indexing into the read buffers.
(package private) final AtomicLongArray	readBufferDrainAtWriteCount
(package private) final long[]	readBufferReadCount
(package private) final AtomicReferenceArray<PrivateMaxEntriesMap.Node<K,V>>	readBuffers
(package private) final AtomicLongArray	readBufferWriteCount
(package private) static final long	serialVersionUID
(package private) Collection<V>	values
(package private) final AtomicLong	weightedSize
(package private) static final int	WRITE_BUFFER_DRAIN_THRESHOLD	The maximum number of write operations to perform per amortized drain.
(package private) final Queue<Runnable>	writeBuffer

Constructor Summary

Constructors

Constructor	Description
PrivateMaxEntriesMap(PrivateMaxEntriesMap.Builder<K,V> builder)	Creates an instance based on the builder's configuration.

Method Summary

Modifier and Type	Method	Description
(package private) void	afterRead(PrivateMaxEntriesMap.Node<K,V> node)	Performs the post-processing work required after a read.
(package private) void	afterWrite(Runnable task)	Performs the post-processing work required after a write.
(package private) void	applyRead(PrivateMaxEntriesMap.Node<K,V> node)	Updates the node's location in the page replacement policy.
long	capacity()	Retrieves the maximum capacity of the map.
(package private) static int	ceilingNextPowerOfTwo(int x)
(package private) static void	checkArgument(boolean expression)	Ensures that the argument expression is true.
(package private) static void	checkNotNull(Object o)	Ensures that the object is not null.
(package private) static void	checkState(boolean expression)	Ensures that the state expression is true.
void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
(package private) void	drainBuffers()	Drains the read and write buffers up to an amortized threshold.
(package private) void	drainOnReadIfNeeded(int bufferIndex, long writeCount)	Attempts to drain the buffers if it is determined to be needed when post-processing a read.
(package private) void	drainReadBuffer(int bufferIndex)	Drains the read buffer up to an amortized threshold.
(package private) void	drainReadBuffers()	Drains the read buffers, each up to an amortized threshold.
(package private) void	drainWriteBuffer()	Drains the read buffer up to an amortized threshold.
Set<Map.Entry<K,V>>	entrySet()
(package private) void	evict()	Evicts entries from the map while it exceeds the capacity and appends evicted entries to the notification queue for processing.
V	get(Object key)
(package private) boolean	hasOverflowed()	Determines whether the map has exceeded its capacity.
boolean	isEmpty()
Set<K>	keySet()
(package private) void	makeDead(PrivateMaxEntriesMap.Node<K,V> node)	Atomically transitions the node to the dead state and decrements the weightedSize.
(package private) void	makeRetired(PrivateMaxEntriesMap.Node<K,V> node)	Atomically transitions the node from the alive state to the retired state, if a valid transition.
V	put(K key, V value)
(package private) V	put(K key, V value, boolean onlyIfAbsent)	Adds a node to the list and the data store.
V	putIfAbsent(K key, V value)
(package private) static int	readBufferIndex()	Returns the index to the read buffer to record into.
private static int	readBufferIndex(int bufferIndex, int entryIndex)
private void	readObject(ObjectInputStream stream)
(package private) long	recordRead(int bufferIndex, PrivateMaxEntriesMap.Node<K,V> node)	Records a read in the buffer and return its write count.
V	remove(Object key)
boolean	remove(Object key, Object value)
V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
void	setCapacity(long capacity)	Sets the maximum capacity of the map and eagerly evicts entries until it shrinks to the appropriate size.
int	size()
(package private) void	tryToDrainBuffers()	Attempts to acquire the eviction lock and apply the pending operations, up to the amortized threshold, to the page replacement policy.
(package private) boolean	tryToRetire(PrivateMaxEntriesMap.Node<K,V> node, PrivateMaxEntriesMap.WeightedValue<V> expect)	Attempts to transition the node from the alive state to the retired state.
Collection<V>	values()
(package private) Object	writeReplace()

Methods inherited from class AbstractMap

clone, equals, hashCode, putAll, toString

Methods inherited from class Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface ConcurrentMap

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, replaceAll

Methods inherited from interface Map

equals, hashCode, putAll

Field Details

NCPU

static final int NCPU

The number of CPUs

MAXIMUM_CAPACITY

static final long MAXIMUM_CAPACITY

The maximum capacity of the map.

See Also:

• Constant Field Values

NUMBER_OF_READ_BUFFERS

static final int NUMBER_OF_READ_BUFFERS

The number of read buffers to use. The max of 4 was introduced due to databind#3665.

READ_BUFFERS_MASK

static final int READ_BUFFERS_MASK

Mask value for indexing into the read buffers.

READ_BUFFER_THRESHOLD

static final int READ_BUFFER_THRESHOLD

The number of pending read operations before attempting to drain. The threshold of 4 was introduced due to databind#3665.

See Also:

• Constant Field Values

READ_BUFFER_DRAIN_THRESHOLD

static final int READ_BUFFER_DRAIN_THRESHOLD

The maximum number of read operations to perform per amortized drain.

See Also:

• Constant Field Values

READ_BUFFER_SIZE

static final int READ_BUFFER_SIZE

The maximum number of pending reads per buffer.

See Also:

• Constant Field Values

READ_BUFFER_INDEX_MASK

static final int READ_BUFFER_INDEX_MASK

Mask value for indexing into the read buffer.

See Also:

• Constant Field Values

WRITE_BUFFER_DRAIN_THRESHOLD

static final int WRITE_BUFFER_DRAIN_THRESHOLD

The maximum number of write operations to perform per amortized drain.

See Also:

• Constant Field Values

data

final ConcurrentMap<K, PrivateMaxEntriesMap.Node<K,V>> data

concurrencyLevel

final int concurrencyLevel

readBufferReadCount

final long[] readBufferReadCount

evictionDeque

final LinkedDeque<PrivateMaxEntriesMap.Node<K,V>> evictionDeque

weightedSize

final AtomicLong weightedSize

capacity

final AtomicLong capacity

evictionLock

final Lock evictionLock

writeBuffer

final Queue<Runnable> writeBuffer

readBufferWriteCount

final AtomicLongArray readBufferWriteCount

readBufferDrainAtWriteCount

final AtomicLongArray readBufferDrainAtWriteCount

readBuffers

final AtomicReferenceArray<PrivateMaxEntriesMap.Node<K,V>> readBuffers

drainStatus

final AtomicReference<PrivateMaxEntriesMap.DrainStatus> drainStatus

keySet

transient Set<K> keySet

values

transient Collection<V> values

entrySet

transient Set<Map.Entry<K,V>> entrySet

serialVersionUID

static final long serialVersionUID

See Also:

• Constant Field Values

Constructor Details

PrivateMaxEntriesMap

PrivateMaxEntriesMap(PrivateMaxEntriesMap.Builder<K,V> builder)

Creates an instance based on the builder's configuration.

Method Details

ceilingNextPowerOfTwo

static int ceilingNextPowerOfTwo(int x)

readBufferIndex

private static int readBufferIndex(int bufferIndex,
 int entryIndex)

checkNotNull

static void checkNotNull(Object o)

Ensures that the object is not null.

checkArgument

static void checkArgument(boolean expression)

Ensures that the argument expression is true.

checkState

static void checkState(boolean expression)

Ensures that the state expression is true.

capacity

public long capacity()

Retrieves the maximum capacity of the map.

Returns:

the maximum capacity

setCapacity

public void setCapacity(long capacity)

Sets the maximum capacity of the map and eagerly evicts entries until it shrinks to the appropriate size.

Parameters:

capacity - the maximum capacity of the map

Throws:

IllegalArgumentException - if the capacity is negative

hasOverflowed

boolean hasOverflowed()

Determines whether the map has exceeded its capacity.

evict

void evict()

Evicts entries from the map while it exceeds the capacity and appends evicted entries to the notification queue for processing.

afterRead

void afterRead(PrivateMaxEntriesMap.Node<K,V> node)

Performs the post-processing work required after a read.

Parameters:

node - the entry in the page replacement policy

readBufferIndex

static int readBufferIndex()

Returns the index to the read buffer to record into.

recordRead

long recordRead(int bufferIndex,
 PrivateMaxEntriesMap.Node<K,V> node)

Records a read in the buffer and return its write count.

Parameters:

bufferIndex - the index to the chosen read buffer

node - the entry in the page replacement policy

Returns:

the number of writes on the chosen read buffer

drainOnReadIfNeeded

void drainOnReadIfNeeded(int bufferIndex,
 long writeCount)

Attempts to drain the buffers if it is determined to be needed when post-processing a read.

Parameters:

bufferIndex - the index to the chosen read buffer

writeCount - the number of writes on the chosen read buffer

afterWrite

void afterWrite(Runnable task)

Performs the post-processing work required after a write.

Parameters:

task - the pending operation to be applied

tryToDrainBuffers

void tryToDrainBuffers()

Attempts to acquire the eviction lock and apply the pending operations, up to the amortized threshold, to the page replacement policy.

drainBuffers

void drainBuffers()

Drains the read and write buffers up to an amortized threshold.

drainReadBuffers

void drainReadBuffers()

Drains the read buffers, each up to an amortized threshold.

drainReadBuffer

void drainReadBuffer(int bufferIndex)

Drains the read buffer up to an amortized threshold.

applyRead

void applyRead(PrivateMaxEntriesMap.Node<K,V> node)

Updates the node's location in the page replacement policy.

drainWriteBuffer

void drainWriteBuffer()

Drains the read buffer up to an amortized threshold.

tryToRetire

boolean tryToRetire(PrivateMaxEntriesMap.Node<K,V> node,
 PrivateMaxEntriesMap.WeightedValue<V> expect)

Attempts to transition the node from the alive state to the retired state.

Parameters:

node - the entry in the page replacement policy

expect - the expected weighted value

Returns:

if successful

makeRetired

void makeRetired(PrivateMaxEntriesMap.Node<K,V> node)

Atomically transitions the node from the alive state to the retired state, if a valid transition.

Parameters:

node - the entry in the page replacement policy

makeDead

void makeDead(PrivateMaxEntriesMap.Node<K,V> node)

Atomically transitions the node to the dead state and decrements the weightedSize.

Parameters:

node - the entry in the page replacement policy

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

Overrides:

isEmpty in class AbstractMap<K,V>

size

public int size()

Specified by:

size in interface Map<K,V>

Overrides:

size in class AbstractMap<K,V>

clear

public void clear()

Specified by:

clear in interface Map<K,V>

Overrides:

clear in class AbstractMap<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

Overrides:

containsKey in class AbstractMap<K,V>

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

Overrides:

containsValue in class AbstractMap<K,V>

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

Overrides:

get in class AbstractMap<K,V>

put

public V put(K key,
 V value)

Specified by:

put in interface Map<K,V>

Overrides:

put in class AbstractMap<K,V>

putIfAbsent

public V putIfAbsent(K key,
 V value)

Specified by:

putIfAbsent in interface ConcurrentMap<K,V>

Specified by:

putIfAbsent in interface Map<K,V>

put

V put(K key,
 V value,
 boolean onlyIfAbsent)

Adds a node to the list and the data store. If an existing node is found, then its value is updated if allowed.

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

onlyIfAbsent - a write is performed only if the key is not already associated with a value

Returns:

the prior value in the data store or null if no mapping was found

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

Overrides:

remove in class AbstractMap<K,V>

remove

public boolean remove(Object key,
 Object value)

Specified by:

remove in interface ConcurrentMap<K,V>

Specified by:

remove in interface Map<K,V>

replace

public V replace(K key,
 V value)

Specified by:

replace in interface ConcurrentMap<K,V>

Specified by:

replace in interface Map<K,V>

replace

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

Specified by:

replace in interface ConcurrentMap<K,V>

Specified by:

replace in interface Map<K,V>

keySet

public Set<K> keySet()

Specified by:

keySet in interface Map<K,V>

Overrides:

keySet in class AbstractMap<K,V>

values

public Collection<V> values()

Specified by:

values in interface Map<K,V>

Overrides:

values in class AbstractMap<K,V>

entrySet

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

Specified by:

entrySet in interface Map<K,V>

Specified by:

entrySet in class AbstractMap<K,V>

writeReplace

Object writeReplace()

readObject

private void readObject(ObjectInputStream stream)
                 throws InvalidObjectException

Throws:

InvalidObjectException