Class BoundedLocalCache<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

com.github.benmanes.caffeine.cache.BLCHeader.PadDrainStatus<K,V>

com.github.benmanes.caffeine.cache.BLCHeader.DrainStatusRef<K,V>

com.github.benmanes.caffeine.cache.BoundedLocalCache<K,V>

Type Parameters:

K - the type of keys maintained by this cache

V - the type of mapped values

All Implemented Interfaces:

LocalCache<K,V>, ConcurrentMap<K,V>, Map<K,V>

Direct Known Subclasses:

SI, SS, WI, WS

abstract class BoundedLocalCache<K,V>
extends BLCHeader.DrainStatusRef<K,V>
implements LocalCache<K,V>

An in-memory cache implementation that supports full concurrency of retrievals, a high expected concurrency for updates, and multiple ways to bound the cache.

This class is abstract and code generated subclasses provide the complete implementation for a particular configuration. This is to ensure that only the fields and execution paths necessary for a given configuration are used.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) final class	BoundedLocalCache.AddTask	Adds the node to the page replacement policy.
(package private) static final class	BoundedLocalCache.BoundedLocalAsyncCache<K,V>
(package private) static final class	BoundedLocalCache.BoundedLocalAsyncLoadingCache<K,V>
(package private) static final class	BoundedLocalCache.BoundedLocalLoadingCache<K,V>
(package private) static class	BoundedLocalCache.BoundedLocalManualCache<K,V>
(package private) static final class	BoundedLocalCache.BoundedPolicy<K,V>
(package private) static final class	BoundedLocalCache.EntryIterator<K,V>	An adapter to safely externalize the entry iterator.
(package private) static final class	BoundedLocalCache.EntrySetView<K,V>	An adapter to safely externalize the entries.
(package private) static final class	BoundedLocalCache.EntrySpliterator<K,V>	An adapter to safely externalize the entry spliterator.
(package private) static final class	BoundedLocalCache.KeyIterator<K,V>	An adapter to safely externalize the key iterator.
(package private) static final class	BoundedLocalCache.KeySetView<K,V>	An adapter to safely externalize the keys.
(package private) static final class	BoundedLocalCache.KeySpliterator<K,V>	An adapter to safely externalize the key spliterator.
(package private) static final class	BoundedLocalCache.PerformCleanupTask	A reusable task that performs the maintenance work; used to avoid wrapping by ForkJoinPool.
(package private) final class	BoundedLocalCache.RemovalTask	Removes a node from the page replacement policy.
(package private) final class	BoundedLocalCache.UpdateTask	Updates the weighted size.
(package private) static final class	BoundedLocalCache.ValueIterator<K,V>	An adapter to safely externalize the value iterator.
(package private) static final class	BoundedLocalCache.ValueSpliterator<K,V>	An adapter to safely externalize the value spliterator.
(package private) static final class	BoundedLocalCache.ValuesView<K,V>	An adapter to safely externalize the values.

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 Consumer<Node<K,V>>	accessPolicy
(package private) final @Nullable CacheLoader<K,V>	cacheLoader
(package private) final ConcurrentHashMap<Object, Node<K,V>>	data
(package private) final BoundedLocalCache.PerformCleanupTask	drainBuffersTask
(package private) @Nullable Set<Map.Entry<K,V>>	entrySet
(package private) final ReentrantLock	evictionLock
(package private) final Executor	executor
(package private) static final long	EXPIRE_WRITE_TOLERANCE	The maximum time window between entry updates before the expiration must be reordered.
(package private) static final double	HILL_CLIMBER_RESTART_THRESHOLD	The difference in hit rates that restarts the climber.
(package private) static final double	HILL_CLIMBER_STEP_DECAY_RATE	The rate to decrease the step size to adapt by.
(package private) static final double	HILL_CLIMBER_STEP_PERCENT	The percent of the total size to adapt the window by.
(package private) final boolean	isAsync
(package private) @Nullable Set<K>	keySet
(package private) static final Logger	logger
(package private) static final long	MAXIMUM_CAPACITY	The maximum weighted capacity of the map.
(package private) static final long	MAXIMUM_EXPIRY	The maximum duration before an entry expires.
(package private) static final int	NCPU	The number of CPUs
(package private) final NodeFactory<K,V>	nodeFactory
(package private) static final double	PERCENT_MAIN	The initial percent of the maximum weighted capacity dedicated to the main space.
(package private) static final double	PERCENT_MAIN_PROTECTED	The percent of the maximum weighted capacity dedicated to the main's protected space.
(package private) static final int	QUEUE_TRANSFER_THRESHOLD	The maximum number of entries that can be transfered between queues.
(package private) final Buffer<Node<K,V>>	readBuffer
(package private) @Nullable Collection<V>	values
(package private) final Weigher<K,V>	weigher
(package private) static final int	WRITE_BUFFER_MAX	The maximum capacity of the write buffer.
(package private) static final int	WRITE_BUFFER_MIN	The initial capacity of the write buffer.
(package private) static final int	WRITE_BUFFER_RETRIES	The number of attempts to insert into the write buffer before yielding.
(package private) final MpscGrowableArrayQueue<Runnable>	writeBuffer
(package private) final CacheWriter<K,V>	writer

Fields inherited from class BLCHeader.DrainStatusRef

DRAIN_STATUS_OFFSET, drainStatus, IDLE, PROCESSING_TO_IDLE, PROCESSING_TO_REQUIRED, REQUIRED

Fields inherited from class BLCHeader.PadDrainStatus

p000, p001, p002, p003, p004, p005, p006, p007, p008, p009, p010, p011, p012, p013, p014, p015, p016, p017, p018, p019, p020, p021, p022, p023, p024, p025, p026, p027, p028, p029, p030, p031, p032, p033, p034, p035, p036, p037, p038, p039, p040, p041, p042, p043, p044, p045, p046, p047, p048, p049, p050, p051, p052, p053, p054, p055, p056, p057, p058, p059, p060, p061, p062, p063, p064, p065, p066, p067, p068, p069, p070, p071, p072, p073, p074, p075, p076, p077, p078, p079, p080, p081, p082, p083, p084, p085, p086, p087, p088, p089, p090, p091, p092, p093, p094, p095, p096, p097, p098, p099, p100, p101, p102, p103, p104, p105, p106, p107, p108, p109, p110, p111, p112, p113, p114, p115, p116, p117, p118, p119

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	BoundedLocalCache(Caffeine<K,V> builder, @Nullable CacheLoader<K,V> cacheLoader, boolean isAsync)	Creates an instance based on the builder's configuration.

Method Summary

Modifier and Type	Method	Description
protected AccessOrderDeque<Node<K,V>>	accessOrderProbationDeque()
protected AccessOrderDeque<Node<K,V>>	accessOrderProtectedDeque()
protected AccessOrderDeque<Node<K,V>>	accessOrderWindowDeque()
protected long	adjustment()
(package private) boolean	admit(K candidateKey, K victimKey)	Determines if the candidate should be accepted into the main space, as determined by its frequency relative to the victim.
(package private) void	afterRead(Node<K,V> node, long now, boolean recordHit)	Performs the post-processing work required after a read.
(package private) void	afterWrite(Runnable task)	Performs the post-processing work required after a write.
void	cleanUp()	See Cache.cleanUp().
void	clear()
(package private) void	climb()	Adapts the eviction policy to towards the optimal recency / frequency configuration.
protected boolean	collectKeys()	Returns if the keys are weak reference garbage collected.
protected boolean	collectValues()	Returns if the values are weak or soft reference garbage collected.
@Nullable V	compute(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction, boolean recordMiss, boolean recordLoad, boolean recordLoadFailure)	See ConcurrentMap.compute(K, BiFunction).
@Nullable V	computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction, boolean recordStats, boolean recordLoad)	See ConcurrentMap.computeIfAbsent(K, Function).
@Nullable V	computeIfPresent(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)
boolean	containsKey(Object key)
boolean	containsValue(Object value)
(package private) void	decreaseWindow()	Decreases the size of the admission window and increases the main's protected region.
(package private) void	demoteFromMainProtected()	Transfers the nodes from the protected to the probation region if it exceeds the maximum.
(package private) void	determineAdjustment()	Calculates the amount to adapt the window by and sets adjustment() accordingly.
(package private) @Nullable V	doComputeIfAbsent(K key, Object keyRef, Function<? super K, ? extends V> mappingFunction, long[] now, boolean recordStats)	Returns the current value from a computeIfAbsent invocation.
(package private) void	drainKeyReferences()	Drains the weak key references queue.
(package private) void	drainReadBuffer()	Drains the read buffer.
(package private) void	drainValueReferences()	Drains the weak / soft value references queue.
(package private) void	drainWriteBuffer()	Drains the write buffer.
Set<Map.Entry<K,V>>	entrySet()
long	estimatedSize()	See Cache.estimatedSize().
(package private) void	evictEntries()	Evicts entries if the cache exceeds the maximum.
(package private) boolean	evictEntry(Node<K,V> node, RemovalCause cause, long now)	Attempts to evict the entry based on the given removal cause.
(package private) void	evictFromMain(int candidates)	Evicts entries from the main space if the cache exceeds the maximum capacity.
(package private) int	evictFromWindow()	Evicts entries from the window space into the main space while the window size exceeds a maximum.
(package private) Map<K,V>	evictionOrder(int limit, Function<V,V> transformer, boolean hottest)	Returns an unmodifiable snapshot map ordered in eviction order, either ascending or descending.
protected boolean	evicts()	Returns if the cache evicts entries due to a maximum size or weight threshold.
final Executor	executor()	Returns the Executor used by this cache.
Ticker	expirationTicker()	Returns the Ticker used by this cache for expiration.
(package private) void	expireAfterAccessEntries(long now)	Expires entries in the access-order queue.
(package private) void	expireAfterAccessEntries(AccessOrderDeque<Node<K,V>> accessOrderDeque, long now)	Expires entries in an access-order queue.
(package private) Map<K,V>	expireAfterAccessOrder(int limit, Function<V,V> transformer, boolean oldest)	Returns an unmodifiable snapshot map ordered in access expiration order, either ascending or descending.
(package private) long	expireAfterCreate(@Nullable K key, @Nullable V value, Expiry<K,V> expiry, long now)	Returns the expiration time for the entry after being created.
(package private) long	expireAfterRead(Node<K,V> node, @Nullable K key, @Nullable V value, Expiry<K,V> expiry, long now)	Returns the access time for the entry after a read.
(package private) long	expireAfterUpdate(Node<K,V> node, @Nullable K key, @Nullable V value, Expiry<K,V> expiry, long now)	Returns the expiration time for the entry after being updated.
(package private) void	expireAfterWriteEntries(long now)	Expires entries on the write-order queue.
(package private) Map<K,V>	expireAfterWriteOrder(int limit, Function<V,V> transformer, boolean oldest)	Returns an unmodifiable snapshot map ordered in write expiration order, either ascending or descending.
(package private) void	expireEntries()	Expires entries that have expired by access, write, or variable.
protected boolean	expiresAfterAccess()	Returns if the cache expires entries after an access time threshold.
protected long	expiresAfterAccessNanos()	Returns how long after the last access to an entry the map will retain that entry.
protected boolean	expiresAfterWrite()	Returns if the cache expires entries after an write time threshold.
protected long	expiresAfterWriteNanos()	Returns how long after the last write to an entry the map will retain that entry.
protected boolean	expiresVariable()	Returns if the cache expires entries after a variable time threshold.
(package private) void	expireVariableEntries(long now)	Expires entries in the timer wheel.
protected Expiry<K,V>	expiry()
protected boolean	fastpath()	Returns if an access to an entry can skip notifying the eviction policy.
(package private) Map<K,V>	fixedSnapshot(Supplier<Iterator<Node<K,V>>> iteratorSupplier, int limit, Function<V,V> transformer)	Returns an unmodifiable snapshot map ordered by the provided iterator.
protected FrequencySketch<K>	frequencySketch()
@Nullable V	get(Object key)
Map<K,V>	getAllPresent(Iterable<?> keys)	See Cache.getAllPresent(Iterable).
private long	getExpirationDelay(long now)	Returns the duration until the next item expires, or invalid reference Long.MAX_VALUE if none.
@Nullable V	getIfPresent(Object key, boolean recordStats)	See Cache.getIfPresent(Object).
@Nullable V	getIfPresentQuietly(Object key, long[] writeTime)	See Cache.getIfPresent(Object).
(package private) boolean	hasExpired(Node<K,V> node, long now)	Returns if the entry has expired.
boolean	hasRemovalListener()	Returns whether this cache notifies when an entry is removed.
protected boolean	hasWriter()	Returns whether this cache notifies a writer when an entry is modified.
boolean	hasWriteTime()	Returns whether the cache captures the write time of the entry.
protected int	hitsInSample()
(package private) void	increaseWindow()	Increases the size of the admission window by shrinking the portion allocated to the main space.
(package private) final boolean	isComputingAsync(Node<?,?> node)	Returns if the node's value is currently being computed, asynchronously.
boolean	isEmpty()
boolean	isRecordingStats()	Returns whether this cache has statistics enabled.
protected boolean	isWeighted()	Returns if entries may be assigned different weights.
protected ReferenceQueue<K>	keyReferenceQueue()
Set<K>	keySet()
protected long	mainProtectedMaximum()	Returns the maximum weighted size of the main's protected space.
protected long	mainProtectedWeightedSize()	Returns the uncorrected combined weight of the values in the main's protected space.
(package private) void	maintenance(@Nullable Runnable task)	Performs the pending maintenance work and sets the state flags during processing to avoid excess scheduling attempts.
(package private) void	makeDead(Node<K,V> node)	Atomically transitions the node to the dead state and decrements the weightedSize.
(package private) static <K,V> SerializationProxy<K,V>	makeSerializationProxy(BoundedLocalCache<?,?> cache, boolean isWeighted)	Creates a serialization proxy based on the common configuration shared by all cache types.
protected long	maximum()	Returns the maximum weighted size.
@Nullable V	merge(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction)
protected int	missesInSample()
void	notifyRemoval(@Nullable K key, @Nullable V value, RemovalCause cause)	Asynchronously sends a removal notification to the listener.
(package private) void	onAccess(Node<K,V> node)	Updates the node's location in the page replacement policy.
protected @Nullable Pacer	pacer()	Returns the Pacer used to schedule the maintenance task.
(package private) void	performCleanUp(@Nullable Runnable task)	Performs the maintenance work, blocking until the lock is acquired.
protected double	previousSampleHitRate()
@Nullable V	put(K key, V value)
@Nullable V	put(K key, V value, boolean notifyWriter)	See Cache.put(Object, Object).
(package private) @Nullable V	put(K key, V value, Expiry<K,V> expiry, boolean notifyWriter, boolean onlyIfAbsent)	Adds a node to the policy and the data store.
@Nullable V	putIfAbsent(K key, V value)
protected boolean	refreshAfterWrite()	Returns if the cache refreshes entries after an write time threshold.
protected long	refreshAfterWriteNanos()	Returns how long after the last write an entry becomes a candidate for refresh.
(package private) void	refreshIfNeeded(Node<K,V> node, long now)	Asynchronously refreshes the entry if eligible.
(package private) @Nullable V	remap(K key, Object keyRef, BiFunction<? super K, ? super V, ? extends V> remappingFunction, long[] now, boolean computeIfAbsent)	Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).
RemovalListener<K,V>	removalListener()	Returns the RemovalListener used by this cache.
@Nullable V	remove(Object key)
boolean	remove(Object key, Object value)
(package private) void	removeNode(Node<K,V> node, long now)
(package private) static <K,V> void	reorder(LinkedDeque<Node<K,V>> deque, Node<K,V> node)	Updates the node's location in the policy's deque.
(package private) void	reorderProbation(Node<K,V> node)	Promote the node from probation to protected on an access.
@Nullable V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
void	replaceAll(BiFunction<? super K, ? super V, ? extends V> function)
protected int	sampleCount()
(package private) void	scheduleAfterWrite()	Conditionally schedules the asynchronous maintenance task after a write operation.
(package private) void	scheduleDrainBuffers()	Attempts to schedule an asynchronous task to apply the pending operations to the page replacement policy.
(package private) void	setAccessTime(Node<K,V> node, long now)
protected void	setAdjustment(long amount)
protected void	setExpiresAfterAccessNanos(long expireAfterAccessNanos)
protected void	setExpiresAfterWriteNanos(long expireAfterWriteNanos)
protected void	setHitsInSample(int hitCount)
protected void	setMainProtectedMaximum(long maximum)
protected void	setMainProtectedWeightedSize(long weightedSize)
protected void	setMaximum(long maximum)
(package private) void	setMaximumSize(long maximum)	Sets the maximum weighted size of the cache.
protected void	setMissesInSample(int missCount)
protected void	setPreviousSampleHitRate(double hitRate)
protected void	setRefreshAfterWriteNanos(long refreshAfterWriteNanos)
protected void	setSampleCount(int sampleCount)
protected void	setStepSize(double stepSize)
(package private) void	setVariableTime(Node<K,V> node, long expirationTime)
protected void	setWeightedSize(long weightedSize)
protected void	setWindowMaximum(long maximum)
protected void	setWindowWeightedSize(long weightedSize)
(package private) void	setWriteTime(Node<K,V> node, long now)
int	size()
(package private) boolean	skipReadBuffer()	Returns if the cache should bypass the read buffer.
StatsCounter	statsCounter()	Returns the StatsCounter used by this cache.
Ticker	statsTicker()	Returns the Ticker used by this cache for statistics.
protected double	stepSize()
protected TimerWheel<K,V>	timerWheel()
(package private) void	tryExpireAfterRead(Node<K,V> node, @Nullable K key, @Nullable V value, Expiry<K,V> expiry, long now)	Attempts to update the access time for the entry after a read.
protected ReferenceQueue<V>	valueReferenceQueue()
Collection<V>	values()
(package private) Map<K,V>	variableSnapshot(boolean ascending, int limit, Function<V,V> transformer)	Returns an unmodifiable snapshot map roughly ordered by the expiration time.
protected long	weightedSize()	Returns the combined weight of the values in the cache (may be negative).
protected long	windowMaximum()	Returns the maximum weighted size of the window space.
protected long	windowWeightedSize()	Returns the uncorrected combined weight of the values in the window space.
protected WriteOrderDeque<Node<K,V>>	writeOrderDeque()

Methods inherited from class BLCHeader.DrainStatusRef

casDrainStatus, drainStatus, lazySetDrainStatus, shouldDrainBuffers

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

forEach, getOrDefault

Methods inherited from interface LocalCache

compute, computeIfAbsent, invalidateAll, statsAware, statsAware, statsAware

Methods inherited from interface Map

equals, hashCode, putAll

Field Details

logger

static final Logger logger

NCPU

static final int NCPU

The number of CPUs

WRITE_BUFFER_MIN

static final int WRITE_BUFFER_MIN

The initial capacity of the write buffer.

See Also:

• Constant Field Values

WRITE_BUFFER_MAX

static final int WRITE_BUFFER_MAX

The maximum capacity of the write buffer.

WRITE_BUFFER_RETRIES

static final int WRITE_BUFFER_RETRIES

The number of attempts to insert into the write buffer before yielding.

See Also:

• Constant Field Values

MAXIMUM_CAPACITY

static final long MAXIMUM_CAPACITY

The maximum weighted capacity of the map.

See Also:

• Constant Field Values

PERCENT_MAIN

static final double PERCENT_MAIN

The initial percent of the maximum weighted capacity dedicated to the main space.

See Also:

• Constant Field Values

PERCENT_MAIN_PROTECTED

static final double PERCENT_MAIN_PROTECTED

The percent of the maximum weighted capacity dedicated to the main's protected space.

See Also:

• Constant Field Values

HILL_CLIMBER_RESTART_THRESHOLD

static final double HILL_CLIMBER_RESTART_THRESHOLD

The difference in hit rates that restarts the climber.

See Also:

• Constant Field Values

HILL_CLIMBER_STEP_PERCENT

static final double HILL_CLIMBER_STEP_PERCENT

The percent of the total size to adapt the window by.

See Also:

• Constant Field Values

HILL_CLIMBER_STEP_DECAY_RATE

static final double HILL_CLIMBER_STEP_DECAY_RATE

The rate to decrease the step size to adapt by.

See Also:

• Constant Field Values

QUEUE_TRANSFER_THRESHOLD

static final int QUEUE_TRANSFER_THRESHOLD

The maximum number of entries that can be transfered between queues.

See Also:

• Constant Field Values

EXPIRE_WRITE_TOLERANCE

static final long EXPIRE_WRITE_TOLERANCE

The maximum time window between entry updates before the expiration must be reordered.

MAXIMUM_EXPIRY

static final long MAXIMUM_EXPIRY

The maximum duration before an entry expires.

See Also:

• Constant Field Values

writeBuffer

final MpscGrowableArrayQueue<Runnable> writeBuffer

data

final ConcurrentHashMap<Object, Node<K,V>> data

cacheLoader

final @Nullable CacheLoader<K,V> cacheLoader

drainBuffersTask

final BoundedLocalCache.PerformCleanupTask drainBuffersTask

accessPolicy

final Consumer<Node<K,V>> accessPolicy

readBuffer

final Buffer<Node<K,V>> readBuffer

nodeFactory

final NodeFactory<K,V> nodeFactory

evictionLock

final ReentrantLock evictionLock

writer

final CacheWriter<K,V> writer

weigher

final Weigher<K,V> weigher

executor

final Executor executor

isAsync

final boolean isAsync

keySet

transient @Nullable Set<K> keySet

values

transient @Nullable Collection<V> values

entrySet

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

Constructor Details

BoundedLocalCache

protected BoundedLocalCache(Caffeine<K,V> builder,
 @Nullable CacheLoader<K,V> cacheLoader,
 boolean isAsync)

Creates an instance based on the builder's configuration.

Method Details

isComputingAsync

final boolean isComputingAsync(Node<?,?> node)

Returns if the node's value is currently being computed, asynchronously.

accessOrderWindowDeque

protected AccessOrderDeque<Node<K,V>> accessOrderWindowDeque()

accessOrderProbationDeque

protected AccessOrderDeque<Node<K,V>> accessOrderProbationDeque()

accessOrderProtectedDeque

protected AccessOrderDeque<Node<K,V>> accessOrderProtectedDeque()

writeOrderDeque

protected WriteOrderDeque<Node<K,V>> writeOrderDeque()

executor

public final Executor executor()

Description copied from interface: LocalCache

Returns the Executor used by this cache.

Specified by:

executor in interface LocalCache<K,V>

hasWriter

protected boolean hasWriter()

Returns whether this cache notifies a writer when an entry is modified.

isRecordingStats

public boolean isRecordingStats()

Description copied from interface: LocalCache

Returns whether this cache has statistics enabled.

Specified by:

isRecordingStats in interface LocalCache<K,V>

statsCounter

public StatsCounter statsCounter()

Description copied from interface: LocalCache

Returns the StatsCounter used by this cache.

Specified by:

statsCounter in interface LocalCache<K,V>

statsTicker

public Ticker statsTicker()

Description copied from interface: LocalCache

Returns the Ticker used by this cache for statistics.

Specified by:

statsTicker in interface LocalCache<K,V>

removalListener

public RemovalListener<K,V> removalListener()

Description copied from interface: LocalCache

Returns the RemovalListener used by this cache.

Specified by:

removalListener in interface LocalCache<K,V>

hasRemovalListener

public boolean hasRemovalListener()

Description copied from interface: LocalCache

Returns whether this cache notifies when an entry is removed.

Specified by:

hasRemovalListener in interface LocalCache<K,V>

notifyRemoval

public void notifyRemoval(@Nullable K key,
 @Nullable V value,
 RemovalCause cause)

Description copied from interface: LocalCache

Asynchronously sends a removal notification to the listener.

Specified by:

notifyRemoval in interface LocalCache<K,V>

collectKeys

protected boolean collectKeys()

Returns if the keys are weak reference garbage collected.

collectValues

protected boolean collectValues()

Returns if the values are weak or soft reference garbage collected.

keyReferenceQueue

protected ReferenceQueue<K> keyReferenceQueue()

valueReferenceQueue

protected ReferenceQueue<V> valueReferenceQueue()

pacer

protected @Nullable Pacer pacer()

Returns the Pacer used to schedule the maintenance task.

expiresVariable

protected boolean expiresVariable()

Returns if the cache expires entries after a variable time threshold.

expiresAfterAccess

protected boolean expiresAfterAccess()

Returns if the cache expires entries after an access time threshold.

expiresAfterAccessNanos

protected long expiresAfterAccessNanos()

Returns how long after the last access to an entry the map will retain that entry.

setExpiresAfterAccessNanos

protected void setExpiresAfterAccessNanos(long expireAfterAccessNanos)

expiresAfterWrite

protected boolean expiresAfterWrite()

Returns if the cache expires entries after an write time threshold.

expiresAfterWriteNanos

protected long expiresAfterWriteNanos()

Returns how long after the last write to an entry the map will retain that entry.

setExpiresAfterWriteNanos

protected void setExpiresAfterWriteNanos(long expireAfterWriteNanos)

refreshAfterWrite

protected boolean refreshAfterWrite()

Returns if the cache refreshes entries after an write time threshold.

refreshAfterWriteNanos

protected long refreshAfterWriteNanos()

Returns how long after the last write an entry becomes a candidate for refresh.

setRefreshAfterWriteNanos

protected void setRefreshAfterWriteNanos(long refreshAfterWriteNanos)

hasWriteTime

public boolean hasWriteTime()

Description copied from interface: LocalCache

Returns whether the cache captures the write time of the entry.

Specified by:

hasWriteTime in interface LocalCache<K,V>

expiry

protected Expiry<K,V> expiry()

expirationTicker

public Ticker expirationTicker()

Description copied from interface: LocalCache

Returns the Ticker used by this cache for expiration.

Specified by:

expirationTicker in interface LocalCache<K,V>

timerWheel

protected TimerWheel<K,V> timerWheel()

evicts

protected boolean evicts()

Returns if the cache evicts entries due to a maximum size or weight threshold.

isWeighted

protected boolean isWeighted()

Returns if entries may be assigned different weights.

frequencySketch

protected FrequencySketch<K> frequencySketch()

fastpath

protected boolean fastpath()

Returns if an access to an entry can skip notifying the eviction policy.

maximum

protected long maximum()

Returns the maximum weighted size.

windowMaximum

protected long windowMaximum()

Returns the maximum weighted size of the window space.

mainProtectedMaximum

protected long mainProtectedMaximum()

Returns the maximum weighted size of the main's protected space.

setMaximum

protected void setMaximum(long maximum)

setWindowMaximum

protected void setWindowMaximum(long maximum)

setMainProtectedMaximum

protected void setMainProtectedMaximum(long maximum)

weightedSize

protected long weightedSize()

Returns the combined weight of the values in the cache (may be negative).

windowWeightedSize

protected long windowWeightedSize()

Returns the uncorrected combined weight of the values in the window space.

mainProtectedWeightedSize

protected long mainProtectedWeightedSize()

Returns the uncorrected combined weight of the values in the main's protected space.

setWeightedSize

protected void setWeightedSize(long weightedSize)

setWindowWeightedSize

protected void setWindowWeightedSize(long weightedSize)

setMainProtectedWeightedSize

protected void setMainProtectedWeightedSize(long weightedSize)

hitsInSample

protected int hitsInSample()

missesInSample

protected int missesInSample()

sampleCount

protected int sampleCount()

stepSize

protected double stepSize()

previousSampleHitRate

protected double previousSampleHitRate()

adjustment

protected long adjustment()

setHitsInSample

protected void setHitsInSample(int hitCount)

setMissesInSample

protected void setMissesInSample(int missCount)

setSampleCount

protected void setSampleCount(int sampleCount)

setStepSize

protected void setStepSize(double stepSize)

setPreviousSampleHitRate

protected void setPreviousSampleHitRate(double hitRate)

setAdjustment

protected void setAdjustment(long amount)

setMaximumSize

void setMaximumSize(long maximum)

Sets the maximum weighted size of the cache. The caller may need to perform a maintenance cycle to eagerly evicts entries until the cache shrinks to the appropriate size.

evictEntries

void evictEntries()

Evicts entries if the cache exceeds the maximum.

evictFromWindow

int evictFromWindow()

Evicts entries from the window space into the main space while the window size exceeds a maximum.

Returns:

the number of candidate entries evicted from the window space

evictFromMain

void evictFromMain(int candidates)

Evicts entries from the main space if the cache exceeds the maximum capacity. The main space determines whether admitting an entry (coming from the window space) is preferable to retaining the eviction policy's victim. This decision is made using a frequency filter so that the least frequently used entry is removed. The window space's candidates were previously placed in the MRU position and the eviction policy's victim is at the LRU position. The two ends of the queue are evaluated while an eviction is required. The number of remaining candidates is provided and decremented on eviction, so that when there are no more candidates the victim is evicted.

Parameters:

candidates - the number of candidate entries evicted from the window space

admit

boolean admit(K candidateKey,
 K victimKey)

Determines if the candidate should be accepted into the main space, as determined by its frequency relative to the victim. A small amount of randomness is used to protect against hash collision attacks, where the victim's frequency is artificially raised so that no new entries are admitted.

Parameters:

candidateKey - the key for the entry being proposed for long term retention

victimKey - the key for the entry chosen by the eviction policy for replacement

Returns:

if the candidate should be admitted and the victim ejected

expireEntries

void expireEntries()

Expires entries that have expired by access, write, or variable.

expireAfterAccessEntries

void expireAfterAccessEntries(long now)

Expires entries in the access-order queue.

expireAfterAccessEntries

void expireAfterAccessEntries(AccessOrderDeque<Node<K,V>> accessOrderDeque,
 long now)

Expires entries in an access-order queue.

expireAfterWriteEntries

void expireAfterWriteEntries(long now)

Expires entries on the write-order queue.

expireVariableEntries

void expireVariableEntries(long now)

Expires entries in the timer wheel.

getExpirationDelay

private long getExpirationDelay(long now)

Returns the duration until the next item expires, or

invalid reference

Long.MAX_VALUE

if none.

hasExpired

boolean hasExpired(Node<K,V> node,
 long now)

Returns if the entry has expired.

evictEntry

boolean evictEntry(Node<K,V> node,
 RemovalCause cause,
 long now)

Attempts to evict the entry based on the given removal cause. A removal due to may be ignored if the entry was updated and is no longer eligible for eviction.

Parameters:

node - the entry to evict

cause - the reason to evict

now - the current time, used only if expiring

Returns:

if the entry was evicted

climb

void climb()

Adapts the eviction policy to towards the optimal recency / frequency configuration.

determineAdjustment

void determineAdjustment()

Calculates the amount to adapt the window by and sets adjustment() accordingly.

increaseWindow

void increaseWindow()

Increases the size of the admission window by shrinking the portion allocated to the main space. As the main space is partitioned into probation and protected regions (80% / 20%), for simplicity only the protected is reduced. If the regions exceed their maximums, this may cause protected items to be demoted to the probation region and probation items to be demoted to the admission window.

decreaseWindow

void decreaseWindow()

Decreases the size of the admission window and increases the main's protected region.

demoteFromMainProtected

void demoteFromMainProtected()

Transfers the nodes from the protected to the probation region if it exceeds the maximum.

afterRead

void afterRead(Node<K,V> node,
 long now,
 boolean recordHit)

Performs the post-processing work required after a read.

Parameters:

node - the entry in the page replacement policy

now - the current time, in nanoseconds

recordHit - if the hit count should be incremented

skipReadBuffer

boolean skipReadBuffer()

Returns if the cache should bypass the read buffer.

refreshIfNeeded

void refreshIfNeeded(Node<K,V> node,
 long now)

Asynchronously refreshes the entry if eligible.

Parameters:

node - the entry in the cache to refresh

now - the current time, in nanoseconds

expireAfterCreate

long expireAfterCreate(@Nullable K key,
 @Nullable V value,
 Expiry<K,V> expiry,
 long now)

Returns the expiration time for the entry after being created.

Parameters:

key - the key of the entry that was created

value - the value of the entry that was created

expiry - the calculator for the expiration time

now - the current time, in nanoseconds

Returns:

the expiration time

expireAfterUpdate

long expireAfterUpdate(Node<K,V> node,
 @Nullable K key,
 @Nullable V value,
 Expiry<K,V> expiry,
 long now)

Returns the expiration time for the entry after being updated.

Parameters:

node - the entry in the page replacement policy

key - the key of the entry that was updated

value - the value of the entry that was updated

expiry - the calculator for the expiration time

now - the current time, in nanoseconds

Returns:

the expiration time

expireAfterRead

long expireAfterRead(Node<K,V> node,
 @Nullable K key,
 @Nullable V value,
 Expiry<K,V> expiry,
 long now)

Returns the access time for the entry after a read.

Parameters:

node - the entry in the page replacement policy

key - the key of the entry that was read

value - the value of the entry that was read

expiry - the calculator for the expiration time

now - the current time, in nanoseconds

Returns:

the expiration time

tryExpireAfterRead

void tryExpireAfterRead(Node<K,V> node,
 @Nullable K key,
 @Nullable V value,
 Expiry<K,V> expiry,
 long now)

Attempts to update the access time for the entry after a read.

Parameters:

node - the entry in the page replacement policy

key - the key of the entry that was read

value - the value of the entry that was read

expiry - the calculator for the expiration time

now - the current time, in nanoseconds

setVariableTime

void setVariableTime(Node<K,V> node,
 long expirationTime)

setWriteTime

void setWriteTime(Node<K,V> node,
 long now)

setAccessTime

void setAccessTime(Node<K,V> node,
 long now)

afterWrite

void afterWrite(Runnable task)

Performs the post-processing work required after a write.

Parameters:

task - the pending operation to be applied

scheduleAfterWrite

void scheduleAfterWrite()

Conditionally schedules the asynchronous maintenance task after a write operation. If the task status was IDLE or REQUIRED then the maintenance task is scheduled immediately. If it is already processing then it is set to transition to REQUIRED upon completion so that a new execution is triggered by the next operation.

scheduleDrainBuffers

void scheduleDrainBuffers()

Attempts to schedule an asynchronous task to apply the pending operations to the page replacement policy. If the executor rejects the task then it is run directly.

cleanUp

public void cleanUp()

Description copied from interface: LocalCache

See Cache.cleanUp().

Specified by:

cleanUp in interface LocalCache<K,V>

performCleanUp

void performCleanUp(@Nullable Runnable task)

Performs the maintenance work, blocking until the lock is acquired. Any exception thrown, such as by CacheWriter.delete(K, V, RemovalCause), is propagated to the caller.

Parameters:

task - an additional pending task to run, or null if not present

maintenance

void maintenance(@Nullable Runnable task)

Performs the pending maintenance work and sets the state flags during processing to avoid excess scheduling attempts. The read buffer, write buffer, and reference queues are drained, followed by expiration, and size-based eviction.

Parameters:

task - an additional pending task to run, or null if not present

drainKeyReferences

void drainKeyReferences()

Drains the weak key references queue.

drainValueReferences

void drainValueReferences()

Drains the weak / soft value references queue.

drainReadBuffer

void drainReadBuffer()

Drains the read buffer.

onAccess

void onAccess(Node<K,V> node)

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

reorderProbation

void reorderProbation(Node<K,V> node)

Promote the node from probation to protected on an access.

reorder

static <K,V> void reorder(LinkedDeque<Node<K,V>> deque,
 Node<K,V> node)

Updates the node's location in the policy's deque.

drainWriteBuffer

void drainWriteBuffer()

Drains the write buffer.

makeDead

void makeDead(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>

estimatedSize

public long estimatedSize()

Description copied from interface: LocalCache

See Cache.estimatedSize().

Specified by:

estimatedSize in interface LocalCache<K,V>

clear

public void clear()

Specified by:

clear in interface Map<K,V>

Overrides:

clear in class AbstractMap<K,V>

removeNode

void removeNode(Node<K,V> node,
 long now)

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 @Nullable V get(Object key)

Specified by:

get in interface Map<K,V>

Overrides:

get in class AbstractMap<K,V>

getIfPresent

public @Nullable V getIfPresent(Object key,
 boolean recordStats)

Description copied from interface: LocalCache

See Cache.getIfPresent(Object). This method differs by accepting a parameter of whether to record the hit and miss statistics based on the success of this operation.

Specified by:

getIfPresent in interface LocalCache<K,V>

getIfPresentQuietly

public @Nullable V getIfPresentQuietly(Object key,
 long[] writeTime)

Description copied from interface: LocalCache

See Cache.getIfPresent(Object). This method differs by not recording the access with the statistics nor the eviction policy, and populates the write time if known.

Specified by:

getIfPresentQuietly in interface LocalCache<K,V>

getAllPresent

public Map<K,V> getAllPresent(Iterable<?> keys)

Description copied from interface: LocalCache

See Cache.getAllPresent(Iterable).

Specified by:

getAllPresent in interface LocalCache<K,V>

put

public @Nullable V put(K key,
 V value)

Specified by:

put in interface Map<K,V>

Overrides:

put in class AbstractMap<K,V>

put

public @Nullable V put(K key,
 V value,
 boolean notifyWriter)

Description copied from interface: LocalCache

See Cache.put(Object, Object). This method differs by allowing the operation to not notify the writer when an entry was inserted or updated.

Specified by:

put in interface LocalCache<K,V>

putIfAbsent

public @Nullable V putIfAbsent(K key,
 V value)

Specified by:

putIfAbsent in interface ConcurrentMap<K,V>

Specified by:

putIfAbsent in interface Map<K,V>

put

@Nullable V put(K key,
 V value,
 Expiry<K,V> expiry,
 boolean notifyWriter,
 boolean onlyIfAbsent)

Adds a node to the policy 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

expiry - the calculator for the expiration time

notifyWriter - if the writer should be notified for an inserted or updated entry

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

Returns:

the prior value in or null if no mapping was found

remove

public @Nullable 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 @Nullable 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>

replaceAll

public void replaceAll(BiFunction<? super K, ? super V, ? extends V> function)

Specified by:

replaceAll in interface ConcurrentMap<K,V>

Specified by:

replaceAll in interface Map<K,V>

computeIfAbsent

public @Nullable V computeIfAbsent(K key,
 Function<? super K, ? extends V> mappingFunction,
 boolean recordStats,
 boolean recordLoad)

Description copied from interface: LocalCache

See ConcurrentMap.computeIfAbsent(K, Function). This method differs by accepting parameters indicating how to record statistics.

Specified by:

computeIfAbsent in interface LocalCache<K,V>

doComputeIfAbsent

@Nullable V doComputeIfAbsent(K key,
 Object keyRef,
 Function<? super K, ? extends V> mappingFunction,
 long[] now,
 boolean recordStats)

Returns the current value from a computeIfAbsent invocation.

computeIfPresent

public @Nullable V computeIfPresent(K key,
 BiFunction<? super K, ? super V, ? extends V> remappingFunction)

Specified by:

computeIfPresent in interface ConcurrentMap<K,V>

Specified by:

computeIfPresent in interface Map<K,V>

compute

public @Nullable V compute(K key,
 BiFunction<? super K, ? super V, ? extends V> remappingFunction,
 boolean recordMiss,
 boolean recordLoad,
 boolean recordLoadFailure)

Description copied from interface: LocalCache

See ConcurrentMap.compute(K, BiFunction). This method differs by accepting parameters indicating whether to record miss and load statistics based on the success of this operation.

Specified by:

compute in interface LocalCache<K,V>

merge

public @Nullable V merge(K key,
 V value,
 BiFunction<? super V, ? super V, ? extends V> remappingFunction)

Specified by:

merge in interface ConcurrentMap<K,V>

Specified by:

merge in interface Map<K,V>

remap

@Nullable V remap(K key,
 Object keyRef,
 BiFunction<? super K, ? super V, ? extends V> remappingFunction,
 long[] now,
 boolean computeIfAbsent)

Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).

An entry that has expired or been reference collected is evicted and the computation continues as if the entry had not been present. This method does not pre-screen and does not wrap the remappingFunction to be statistics aware.

Parameters:

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

keyRef - the key to associate with or a lookup only key if not computeIfAbsent

remappingFunction - the function to compute a value

now - the current time, according to the ticker

computeIfAbsent - if an absent entry can be computed

Returns:

the new value associated with the specified key, or null if none

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>

evictionOrder

Map<K,V> evictionOrder(int limit,
 Function<V,V> transformer,
 boolean hottest)

Returns an unmodifiable snapshot map ordered in eviction order, either ascending or descending. Beware that obtaining the mappings is NOT a constant-time operation.

Parameters:

limit - the maximum number of entries

transformer - a function that unwraps the value

hottest - the iteration order

Returns:

an unmodifiable snapshot in a specified order

expireAfterAccessOrder

Map<K,V> expireAfterAccessOrder(int limit,
 Function<V,V> transformer,
 boolean oldest)

Returns an unmodifiable snapshot map ordered in access expiration order, either ascending or descending. Beware that obtaining the mappings is NOT a constant-time operation.

Parameters:

limit - the maximum number of entries

transformer - a function that unwraps the value

oldest - the iteration order

Returns:

an unmodifiable snapshot in a specified order

expireAfterWriteOrder

Map<K,V> expireAfterWriteOrder(int limit,
 Function<V,V> transformer,
 boolean oldest)

Returns an unmodifiable snapshot map ordered in write expiration order, either ascending or descending. Beware that obtaining the mappings is NOT a constant-time operation.

Parameters:

limit - the maximum number of entries

transformer - a function that unwraps the value

oldest - the iteration order

Returns:

an unmodifiable snapshot in a specified order

fixedSnapshot

Map<K,V> fixedSnapshot(Supplier<Iterator<Node<K,V>>> iteratorSupplier,
 int limit,
 Function<V,V> transformer)

Returns an unmodifiable snapshot map ordered by the provided iterator. Beware that obtaining the mappings is NOT a constant-time operation.

Parameters:

iteratorSupplier - the iterator

limit - the maximum number of entries

transformer - a function that unwraps the value

Returns:

an unmodifiable snapshot in the iterator's order

variableSnapshot

Map<K,V> variableSnapshot(boolean ascending,
 int limit,
 Function<V,V> transformer)

Returns an unmodifiable snapshot map roughly ordered by the expiration time. The wheels are evaluated in order, but the timers that fall within the bucket's range are not sorted. Beware that obtaining the mappings is NOT a constant-time operation.

Parameters:

ascending - the direction

limit - the maximum number of entries

transformer - a function that unwraps the value

Returns:

an unmodifiable snapshot in the desired order

makeSerializationProxy

static <K,V> SerializationProxy<K,V> makeSerializationProxy(BoundedLocalCache<?,?> cache,
 boolean isWeighted)

Creates a serialization proxy based on the common configuration shared by all cache types.