Package org.apache.hadoop.hbase.io.hfile

Class LruAdaptiveBlockCache

java.lang.Object

org.apache.hadoop.hbase.io.hfile.LruAdaptiveBlockCache

All Implemented Interfaces:

Iterable<CachedBlock>, HeapSize, BlockCache, FirstLevelBlockCache, ResizableBlockCache

@Private
public class LruAdaptiveBlockCache
extends Object
implements FirstLevelBlockCache

This realisation improve performance of classical LRU cache up to 3 times via reduce GC job.

The classical block cache implementation that is memory-aware using HeapSize, memory-bound using an LRU eviction algorithm, and concurrent: backed by a ConcurrentHashMap and with a non-blocking eviction thread giving constant-time cacheBlock(org.apache.hadoop.hbase.io.hfile.BlockCacheKey, org.apache.hadoop.hbase.io.hfile.Cacheable, boolean) and getBlock(org.apache.hadoop.hbase.io.hfile.BlockCacheKey, boolean, boolean, boolean) operations.

Contains three levels of block priority to allow for scan-resistance and in-memory families ColumnFamilyDescriptorBuilder.setInMemory(boolean) (An in-memory column family is a column family that should be served from memory if possible): single-access, multiple-accesses, and in-memory priority. A block is added with an in-memory priority flag if ColumnFamilyDescriptor.isInMemory(), otherwise a block becomes a single access priority the first time it is read into this block cache. If a block is accessed again while in cache, it is marked as a multiple access priority block. This delineation of blocks is used to prevent scans from thrashing the cache adding a least-frequently-used element to the eviction algorithm.

Each priority is given its own chunk of the total cache to ensure fairness during eviction. Each priority will retain close to its maximum size, however, if any priority is not using its entire chunk the others are able to grow beyond their chunk size.

Instantiated at a minimum with the total size and average block size. All sizes are in bytes. The block size is not especially important as this cache is fully dynamic in its sizing of blocks. It is only used for pre-allocating data structures and in initial heap estimation of the map.

The detailed constructor defines the sizes for the three priorities (they should total to the maximum size defined). It also sets the levels that trigger and control the eviction thread.

The acceptable size is the cache size level which triggers the eviction process to start. It evicts enough blocks to get the size below the minimum size specified.

Eviction happens in a separate thread and involves a single full-scan of the map. It determines how many bytes must be freed to reach the minimum size, and then while scanning determines the fewest least-recently-used blocks necessary from each of the three priorities (would be 3 times bytes to free). It then uses the priority chunk sizes to evict fairly according to the relative sizes and usage.

Adaptive LRU cache lets speed up performance while we are reading much more data than can fit into BlockCache and it is the cause of a high rate of evictions. This in turn leads to heavy Garbage Collector works. So a lot of blocks put into BlockCache but never read, but spending a lot of CPU resources for cleaning. We could avoid this situation via parameters:

hbase.lru.cache.heavy.eviction.count.limit - set how many times we have to run the eviction process that starts to avoid putting data to BlockCache. By default it is 0 and it meats the feature will start at the beginning. But if we have some times short reading the same data and some times long-term reading - we can divide it by this parameter. For example we know that our short reading used to be about 1 minutes, then we have to set the parameter about 10 and it will enable the feature only for long time massive reading (after ~100 seconds). So when we use short-reading and want all of them in the cache we will have it (except for eviction of course). When we use long-term heavy reading the feature will be enabled after some time and bring better performance.

hbase.lru.cache.heavy.eviction.mb.size.limit - set how many bytes in 10 seconds desirable putting into BlockCache (and evicted from it). The feature will try to reach this value and maintain it. Don't try to set it too small because it leads to premature exit from this mode. For powerful CPUs (about 20-40 physical cores) it could be about 400-500 MB. Average system (~10 cores) 200-300 MB. Some weak systems (2-5 cores) may be good with 50-100 MB. How it works: we set the limit and after each ~10 second calculate how many bytes were freed. Overhead = Freed Bytes Sum (MB) * 100 / Limit (MB) - 100; For example we set the limit = 500 and were evicted 2000 MB. Overhead is: 2000 * 100 / 500 - 100 = 300% The feature is going to reduce a percent caching data blocks and fit evicted bytes closer to 100% (500 MB). Some kind of an auto-scaling. If freed bytes less then the limit we have got negative overhead. For example if were freed 200 MB: 200 * 100 / 500 - 100 = -60% The feature will increase the percent of caching blocks. That leads to fit evicted bytes closer to 100% (500 MB). The current situation we can find out in the log of RegionServer: BlockCache evicted (MB): 0, overhead (%): -100, heavy eviction counter: 0, current caching DataBlock (%): 100 - means no eviction, 100% blocks is caching BlockCache evicted (MB): 2000, overhead (%): 300, heavy eviction counter: 1, current caching DataBlock (%): 97 - means eviction begin, reduce of caching blocks by 3%. It help to tune your system and find out what value is better set. Don't try to reach 0% overhead, it is impossible. Quite good 50-100% overhead, it prevents premature exit from this mode.

hbase.lru.cache.heavy.eviction.overhead.coefficient - set how fast we want to get the result. If we know that our reading is heavy for a long time, we don't want to wait and can increase the coefficient and get good performance sooner. But if we aren't sure we can do it slowly and it could prevent premature exit from this mode. So, when the coefficient is higher we can get better performance when heavy reading is stable. But when reading is changing we can adjust to it and set the coefficient to lower value. For example, we set the coefficient = 0.01. It means the overhead (see above) will be multiplied by 0.01 and the result is the value of reducing percent caching blocks. For example, if the overhead = 300% and the coefficient = 0.01, then percent of caching blocks will reduce by 3%. Similar logic when overhead has got negative value (overshooting). Maybe it is just short-term fluctuation and we will try to stay in this mode. It helps avoid premature exit during short-term fluctuation. Backpressure has simple logic: more overshooting - more caching blocks.

Find more information about improvement: https://issues.apache.org/jira/browse/HBASE-23887

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private class	LruAdaptiveBlockCache.BlockBucket	Used to group blocks into priority buckets.
(package private) static class	LruAdaptiveBlockCache.EvictionThread
(package private) static class	LruAdaptiveBlockCache.StatisticsThread

Field Summary

Fields

Modifier and Type	Field	Description
private final float	acceptableFactor	Acceptable size of cache (no evictions if size < acceptable)
private final long	blockSize	Approximate block size
static final long	CACHE_FIXED_OVERHEAD
private int	cacheDataBlockPercent	Percent of cached data blocks
private final AtomicLong	count	Cache access count (sequential ID)
private final LongAdder	dataBlockElements	Current number of cached data block elements
private final LongAdder	dataBlockSize	Current size of data blocks
(package private) static final float	DEFAULT_ACCEPTABLE_FACTOR
(package private) static final int	DEFAULT_CONCURRENCY_LEVEL
private static final float	DEFAULT_HARD_CAPACITY_LIMIT_FACTOR
private static final boolean	DEFAULT_IN_MEMORY_FORCE_MODE
(package private) static final float	DEFAULT_LOAD_FACTOR
private static final int	DEFAULT_LRU_CACHE_HEAVY_EVICTION_COUNT_LIMIT
private static final long	DEFAULT_LRU_CACHE_HEAVY_EVICTION_MB_SIZE_LIMIT
private static final float	DEFAULT_LRU_CACHE_HEAVY_EVICTION_OVERHEAD_COEFFICIENT
private static final long	DEFAULT_MAX_BLOCK_SIZE
private static final float	DEFAULT_MEMORY_FACTOR
private static final float	DEFAULT_MIN_FACTOR
private static final float	DEFAULT_MULTI_FACTOR
private static final float	DEFAULT_SINGLE_FACTOR
private final AtomicLong	elements	Current number of cached elements
private boolean	evictionInProgress	Volatile boolean to track if we are in an eviction process or not
private final ReentrantLock	evictionLock	Eviction lock (locked when eviction in process)
private final LruAdaptiveBlockCache.EvictionThread	evictionThread	Eviction thread
private boolean	forceInMemory	Whether in-memory hfile's data block has higher priority when evicting
private final float	hardCapacityLimitFactor	hard capacity limit
private final int	heavyEvictionCountLimit	Limit of count eviction process when start to avoid to cache blocks
private final long	heavyEvictionMbSizeLimit	Limit of volume eviction process when start to avoid to cache blocks
private final float	heavyEvictionOverheadCoefficient	Adjust auto-scaling via overhead of evition rate
private static final org.slf4j.Logger	LOG
private static final String	LRU_ACCEPTABLE_FACTOR_CONFIG_NAME	Acceptable size of cache (no evictions if size < acceptable)
private static final String	LRU_CACHE_HEAVY_EVICTION_COUNT_LIMIT
private static final String	LRU_CACHE_HEAVY_EVICTION_MB_SIZE_LIMIT
private static final String	LRU_CACHE_HEAVY_EVICTION_OVERHEAD_COEFFICIENT
(package private) static final String	LRU_HARD_CAPACITY_LIMIT_FACTOR_CONFIG_NAME	Hard capacity limit of cache, will reject any put if size > this * acceptable
private static final String	LRU_IN_MEMORY_FORCE_MODE_CONFIG_NAME	Configuration key to force data-block always (except in-memory are too much) cached in memory for in-memory hfile, unlike inMemory, which is a column-family configuration, inMemoryForceMode is a cluster-wide configuration
private static final String	LRU_MAX_BLOCK_SIZE
private static final String	LRU_MEMORY_PERCENTAGE_CONFIG_NAME
private static final String	LRU_MIN_FACTOR_CONFIG_NAME	Percentage of total size that eviction will evict until; e.g.
private static final String	LRU_MULTI_PERCENTAGE_CONFIG_NAME
private static final String	LRU_SINGLE_PERCENTAGE_CONFIG_NAME
private final ConcurrentHashMap<BlockCacheKey,LruCachedBlock>	map	Defined the cache map as ConcurrentHashMap here, because in getBlock(org.apache.hadoop.hbase.io.hfile.BlockCacheKey, boolean, boolean, boolean), we need to guarantee the atomicity of map#computeIfPresent (key, func).
private final long	maxBlockSize
private long	maxSize	Maximum allowable size of cache (block put if size > max, evict)
private final float	memoryFactor	In-memory bucket size
private final float	minFactor	Minimum threshold of cache (when evicting, evict until size < min)
private final float	multiFactor	Multiple access bucket size
private final long	overhead	Overhead of the structure itself
private final ScheduledExecutorService	scheduleThreadPool	Statistics thread schedule pool (for heavy debugging, could remove)
private final float	singleFactor	Single access bucket size
private final AtomicLong	size	Current size of cache
private static final int	STAT_THREAD_PERIOD
private final CacheStats	stats	Cache statistics
private BlockCache	victimHandler	Where to send victims (blocks evicted/missing from the cache).

Constructor Summary

Constructors

Constructor	Description
LruAdaptiveBlockCache(long maxSize, long blockSize)	Default constructor.
LruAdaptiveBlockCache(long maxSize, long blockSize, boolean evictionThread)	Constructor used for testing.
LruAdaptiveBlockCache(long maxSize, long blockSize, boolean evictionThread, int mapInitialSize, float mapLoadFactor, int mapConcurrencyLevel, float minFactor, float acceptableFactor, float singleFactor, float multiFactor, float memoryFactor, float hardLimitFactor, boolean forceInMemory, long maxBlockSize, int heavyEvictionCountLimit, long heavyEvictionMbSizeLimit, float heavyEvictionOverheadCoefficient)	Configurable constructor.
LruAdaptiveBlockCache(long maxSize, long blockSize, boolean evictionThread, org.apache.hadoop.conf.Configuration conf)
LruAdaptiveBlockCache(long maxSize, long blockSize, org.apache.hadoop.conf.Configuration conf)

Method Summary

Modifier and Type	Method	Description
(package private) long	acceptableSize()
private Cacheable	asReferencedHeapBlock(Cacheable buf)	The block cached in LruAdaptiveBlockCache will always be an heap block: on the one side, the heap access will be more faster then off-heap, the small index block or meta block cached in CombinedBlockCache will benefit a lot.
private static void	assertCounterSanity(long mapSize, long counterVal)	Sanity-checking for parity between actual block cache content and metrics.
void	cacheBlock(BlockCacheKey cacheKey, Cacheable buf)	Cache the block with the specified name and buffer.
void	cacheBlock(BlockCacheKey cacheKey, Cacheable buf, boolean inMemory)	Cache the block with the specified name and buffer.
private static long	calculateOverhead(long maxSize, long blockSize, int concurrency)
void	clearCache()	Clears the cache.
boolean	containsBlock(BlockCacheKey cacheKey)	Whether the cache contains block with specified cacheKey
(package private) long	evict()	Eviction method.
boolean	evictBlock(BlockCacheKey cacheKey)	Evict block from cache.
protected long	evictBlock(LruCachedBlock block, boolean evictedByEvictionProcess)	Evict the block, and it will be cached by the victim handler if exists && block may be read again later
int	evictBlocksByHfileName(String hfileName)	Evicts all blocks for a specific HFile.
Cacheable	getBlock(BlockCacheKey cacheKey, boolean caching, boolean repeat, boolean updateCacheMetrics)	Get the buffer of the block with the specified name.
BlockCache[]	getBlockCaches()	Returns The list of sub blockcaches that make up this one; returns null if no sub caches.
long	getBlockCount()	Returns the number of blocks currently cached in the block cache.
int	getCacheDataBlockPercent()
long	getCurrentDataSize()	Returns the occupied size of data blocks, in bytes.
long	getCurrentSize()	Returns the occupied size of the block cache, in bytes.
long	getDataBlockCount()	Returns the number of data blocks currently cached in the block cache.
Map<DataBlockEncoding,Integer>	getEncodingCountsForTest()
(package private) LruAdaptiveBlockCache.EvictionThread	getEvictionThread()
long	getFreeSize()	Returns the free size of the block cache, in bytes.
(package private) Map<BlockCacheKey,LruCachedBlock>	getMapForTests()
long	getMaxSize()	Get the maximum size of this cache.
(package private) long	getOverhead()
CacheStats	getStats()	Get counter statistics for this cache.
long	heapSize()	Return the approximate 'exclusive deep size' of implementing object.
(package private) boolean	isEvictionInProgress()
Iterator<CachedBlock>	iterator()	Returns Iterator over the blocks in the cache.
void	logStats()
private long	memorySize()
private long	minSize()
private long	multiSize()
private void	runEviction()	Multi-threaded call to run the eviction process.
void	setMaxSize(long maxSize)	Sets the max heap size that can be used by the BlockCache.
void	setVictimCache(BlockCache victimCache)	Specifies the secondary cache.
void	shutdown()	Shutdown the cache.
private long	singleSize()
long	size()	Returns the total size of the block cache, in bytes.
String	toString()
private long	updateSizeMetrics(LruCachedBlock cb, boolean evict)	Helper function that updates the local size counter and also updates any per-cf or per-blocktype metrics it can discern from given LruCachedBlock

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.hadoop.hbase.io.hfile.BlockCache

blockFitsIntoTheCache, cacheBlock, evictBlocksRangeByHfileName, getBlock, getBlockSize, getFullyCachedFiles, getRegionCachedInfo, isAlreadyCached, isCacheEnabled, isMetaBlock, notifyFileCachingCompleted, shouldCacheFile, waitForCacheInitialization

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Details

LOG

private static final org.slf4j.Logger LOG

LRU_MIN_FACTOR_CONFIG_NAME

private static final String LRU_MIN_FACTOR_CONFIG_NAME

Percentage of total size that eviction will evict until; e.g. if set to .8, then we will keep evicting during an eviction run till the cache size is down to 80% of the total.

See Also:

• Constant Field Values

LRU_ACCEPTABLE_FACTOR_CONFIG_NAME

private static final String LRU_ACCEPTABLE_FACTOR_CONFIG_NAME

Acceptable size of cache (no evictions if size < acceptable)

See Also:

• Constant Field Values

LRU_HARD_CAPACITY_LIMIT_FACTOR_CONFIG_NAME

static final String LRU_HARD_CAPACITY_LIMIT_FACTOR_CONFIG_NAME

Hard capacity limit of cache, will reject any put if size > this * acceptable

See Also:

• Constant Field Values

LRU_SINGLE_PERCENTAGE_CONFIG_NAME

private static final String LRU_SINGLE_PERCENTAGE_CONFIG_NAME

See Also:

• Constant Field Values

LRU_MULTI_PERCENTAGE_CONFIG_NAME

private static final String LRU_MULTI_PERCENTAGE_CONFIG_NAME

See Also:

• Constant Field Values

LRU_MEMORY_PERCENTAGE_CONFIG_NAME

private static final String LRU_MEMORY_PERCENTAGE_CONFIG_NAME

See Also:

• Constant Field Values

LRU_IN_MEMORY_FORCE_MODE_CONFIG_NAME

private static final String LRU_IN_MEMORY_FORCE_MODE_CONFIG_NAME

Configuration key to force data-block always (except in-memory are too much) cached in memory for in-memory hfile, unlike inMemory, which is a column-family configuration, inMemoryForceMode is a cluster-wide configuration

See Also:

• Constant Field Values

DEFAULT_LOAD_FACTOR

static final float DEFAULT_LOAD_FACTOR

See Also:

• Constant Field Values

DEFAULT_CONCURRENCY_LEVEL

static final int DEFAULT_CONCURRENCY_LEVEL

See Also:

• Constant Field Values

DEFAULT_MIN_FACTOR

private static final float DEFAULT_MIN_FACTOR

See Also:

• Constant Field Values

DEFAULT_ACCEPTABLE_FACTOR

static final float DEFAULT_ACCEPTABLE_FACTOR

See Also:

• Constant Field Values

DEFAULT_SINGLE_FACTOR

private static final float DEFAULT_SINGLE_FACTOR

See Also:

• Constant Field Values

DEFAULT_MULTI_FACTOR

private static final float DEFAULT_MULTI_FACTOR

See Also:

• Constant Field Values

DEFAULT_MEMORY_FACTOR

private static final float DEFAULT_MEMORY_FACTOR

See Also:

• Constant Field Values

DEFAULT_HARD_CAPACITY_LIMIT_FACTOR

private static final float DEFAULT_HARD_CAPACITY_LIMIT_FACTOR

See Also:

• Constant Field Values

DEFAULT_IN_MEMORY_FORCE_MODE

private static final boolean DEFAULT_IN_MEMORY_FORCE_MODE

See Also:

• Constant Field Values

STAT_THREAD_PERIOD

private static final int STAT_THREAD_PERIOD

See Also:

• Constant Field Values

LRU_MAX_BLOCK_SIZE

private static final String LRU_MAX_BLOCK_SIZE

See Also:

• Constant Field Values

DEFAULT_MAX_BLOCK_SIZE

private static final long DEFAULT_MAX_BLOCK_SIZE

See Also:

• Constant Field Values

LRU_CACHE_HEAVY_EVICTION_COUNT_LIMIT

private static final String LRU_CACHE_HEAVY_EVICTION_COUNT_LIMIT

See Also:

• Constant Field Values

DEFAULT_LRU_CACHE_HEAVY_EVICTION_COUNT_LIMIT

private static final int DEFAULT_LRU_CACHE_HEAVY_EVICTION_COUNT_LIMIT

See Also:

• Constant Field Values

LRU_CACHE_HEAVY_EVICTION_MB_SIZE_LIMIT

private static final String LRU_CACHE_HEAVY_EVICTION_MB_SIZE_LIMIT

See Also:

• Constant Field Values

DEFAULT_LRU_CACHE_HEAVY_EVICTION_MB_SIZE_LIMIT

private static final long DEFAULT_LRU_CACHE_HEAVY_EVICTION_MB_SIZE_LIMIT

See Also:

• Constant Field Values

LRU_CACHE_HEAVY_EVICTION_OVERHEAD_COEFFICIENT

private static final String LRU_CACHE_HEAVY_EVICTION_OVERHEAD_COEFFICIENT

See Also:

• Constant Field Values

DEFAULT_LRU_CACHE_HEAVY_EVICTION_OVERHEAD_COEFFICIENT

private static final float DEFAULT_LRU_CACHE_HEAVY_EVICTION_OVERHEAD_COEFFICIENT

See Also:

• Constant Field Values

map

private final transient ConcurrentHashMap<BlockCacheKey,LruCachedBlock> map

Defined the cache map as ConcurrentHashMap here, because in getBlock(org.apache.hadoop.hbase.io.hfile.BlockCacheKey, boolean, boolean, boolean), we need to guarantee the atomicity of map#computeIfPresent (key, func). Besides, the func method must execute exactly once only when the key is present and under the lock context, otherwise the reference count will be messed up. Notice that the ConcurrentSkipListMap can not guarantee that.

evictionLock

private final transient ReentrantLock evictionLock

Eviction lock (locked when eviction in process)

maxBlockSize

private final long maxBlockSize

evictionInProgress

private volatile boolean evictionInProgress

Volatile boolean to track if we are in an eviction process or not

evictionThread

private final transient LruAdaptiveBlockCache.EvictionThread evictionThread

Eviction thread

scheduleThreadPool

private final transient ScheduledExecutorService scheduleThreadPool

Statistics thread schedule pool (for heavy debugging, could remove)

size

private final AtomicLong size

Current size of cache

dataBlockSize

private final LongAdder dataBlockSize

Current size of data blocks

elements

private final AtomicLong elements

Current number of cached elements

dataBlockElements

private final LongAdder dataBlockElements

Current number of cached data block elements

count

private final AtomicLong count

Cache access count (sequential ID)

hardCapacityLimitFactor

private final float hardCapacityLimitFactor

hard capacity limit

stats

private final CacheStats stats

Cache statistics

maxSize

private long maxSize

Maximum allowable size of cache (block put if size > max, evict)

blockSize

private final long blockSize

Approximate block size

acceptableFactor

private final float acceptableFactor

Acceptable size of cache (no evictions if size < acceptable)

minFactor

private final float minFactor

Minimum threshold of cache (when evicting, evict until size < min)

singleFactor

private final float singleFactor

Single access bucket size

multiFactor

private final float multiFactor

Multiple access bucket size

memoryFactor

private final float memoryFactor

In-memory bucket size

overhead

private final long overhead

Overhead of the structure itself

forceInMemory

private boolean forceInMemory

Whether in-memory hfile's data block has higher priority when evicting

victimHandler

private transient BlockCache victimHandler

Where to send victims (blocks evicted/missing from the cache). This is used only when we use an external cache as L2. Note: See org.apache.hadoop.hbase.io.hfile.MemcachedBlockCache

cacheDataBlockPercent

private volatile int cacheDataBlockPercent

Percent of cached data blocks

heavyEvictionCountLimit

private final int heavyEvictionCountLimit

Limit of count eviction process when start to avoid to cache blocks

heavyEvictionMbSizeLimit

private final long heavyEvictionMbSizeLimit

Limit of volume eviction process when start to avoid to cache blocks

heavyEvictionOverheadCoefficient

private final float heavyEvictionOverheadCoefficient

Adjust auto-scaling via overhead of evition rate

CACHE_FIXED_OVERHEAD

public static final long CACHE_FIXED_OVERHEAD

Constructor Details

LruAdaptiveBlockCache

public LruAdaptiveBlockCache(long maxSize,
 long blockSize)

Default constructor. Specify maximum size and expected average block size (approximation is fine).

All other factors will be calculated based on defaults specified in this class.

Parameters:

maxSize - maximum size of cache, in bytes

blockSize - approximate size of each block, in bytes

LruAdaptiveBlockCache

public LruAdaptiveBlockCache(long maxSize,
 long blockSize,
 boolean evictionThread)

Constructor used for testing. Allows disabling of the eviction thread.

LruAdaptiveBlockCache

public LruAdaptiveBlockCache(long maxSize,
 long blockSize,
 boolean evictionThread,
 org.apache.hadoop.conf.Configuration conf)

LruAdaptiveBlockCache

public LruAdaptiveBlockCache(long maxSize,
 long blockSize,
 org.apache.hadoop.conf.Configuration conf)

LruAdaptiveBlockCache

public LruAdaptiveBlockCache(long maxSize,
 long blockSize,
 boolean evictionThread,
 int mapInitialSize,
 float mapLoadFactor,
 int mapConcurrencyLevel,
 float minFactor,
 float acceptableFactor,
 float singleFactor,
 float multiFactor,
 float memoryFactor,
 float hardLimitFactor,
 boolean forceInMemory,
 long maxBlockSize,
 int heavyEvictionCountLimit,
 long heavyEvictionMbSizeLimit,
 float heavyEvictionOverheadCoefficient)

Configurable constructor. Use this constructor if not using defaults.

Parameters:

maxSize - maximum size of this cache, in bytes

blockSize - expected average size of blocks, in bytes

evictionThread - whether to run evictions in a bg thread or not

mapInitialSize - initial size of backing ConcurrentHashMap

mapLoadFactor - initial load factor of backing ConcurrentHashMap

mapConcurrencyLevel - initial concurrency factor for backing CHM

minFactor - percentage of total size that eviction will evict until

acceptableFactor - percentage of total size that triggers eviction

singleFactor - percentage of total size for single-access blocks

multiFactor - percentage of total size for multiple-access blocks

memoryFactor - percentage of total size for in-memory blocks

hardLimitFactor - hard capacity limit

forceInMemory - in-memory hfile's data block has higher priority when evicting

maxBlockSize - maximum block size for caching

heavyEvictionCountLimit - when starts AdaptiveLRU algoritm work

heavyEvictionMbSizeLimit - how many bytes desirable putting into BlockCache

heavyEvictionOverheadCoefficient - how aggressive AdaptiveLRU will reduce GC

Method Details

setVictimCache

public void setVictimCache(BlockCache victimCache)

Description copied from interface: FirstLevelBlockCache

Specifies the secondary cache. An entry that is evicted from this cache due to a size constraint will be inserted into the victim cache.

Specified by:

setVictimCache in interface FirstLevelBlockCache

Parameters:

victimCache - the second level cache

setMaxSize

public void setMaxSize(long maxSize)

Description copied from interface: ResizableBlockCache

Sets the max heap size that can be used by the BlockCache.

Specified by:

setMaxSize in interface ResizableBlockCache

Parameters:

maxSize - The max heap size.

getCacheDataBlockPercent

public int getCacheDataBlockPercent()

asReferencedHeapBlock

private Cacheable asReferencedHeapBlock(Cacheable buf)

The block cached in LruAdaptiveBlockCache will always be an heap block: on the one side, the heap access will be more faster then off-heap, the small index block or meta block cached in CombinedBlockCache will benefit a lot. on other side, the LruAdaptiveBlockCache size is always calculated based on the total heap size, if caching an off-heap block in LruAdaptiveBlockCache, the heap size will be messed up. Here we will clone the block into an heap block if it's an off-heap block, otherwise just use the original block. The key point is maintain the refCnt of the block (HBASE-22127):
1. if cache the cloned heap block, its refCnt is an totally new one, it's easy to handle;
2. if cache the original heap block, we're sure that it won't be tracked in ByteBuffAllocator's reservoir, if both RPC and LruAdaptiveBlockCache release the block, then it can be garbage collected by JVM, so need a retain here.

Parameters:

buf - the original block

Returns:

an block with an heap memory backend.

cacheBlock

public void cacheBlock(BlockCacheKey cacheKey,
 Cacheable buf,
 boolean inMemory)

Cache the block with the specified name and buffer.

It is assumed this will NOT be called on an already cached block. In rare cases (HBASE-8547) this can happen, for which we compare the buffer contents.

Specified by:

cacheBlock in interface BlockCache

Parameters:

cacheKey - block's cache key

buf - block buffer

inMemory - if block is in-memory

assertCounterSanity

private static void assertCounterSanity(long mapSize,
 long counterVal)

Sanity-checking for parity between actual block cache content and metrics. Intended only for use with TRACE level logging and -ea JVM.

cacheBlock

public void cacheBlock(BlockCacheKey cacheKey,
 Cacheable buf)

Cache the block with the specified name and buffer.

TODO after HBASE-22005, we may cache an block which allocated from off-heap, but our LRU cache sizing is based on heap size, so we should handle this in HBASE-22127. It will introduce an switch whether make the LRU on-heap or not, if so we may need copy the memory to on-heap, otherwise the caching size is based on off-heap.

Specified by:

cacheBlock in interface BlockCache

Parameters:

cacheKey - block's cache key

buf - block buffer

updateSizeMetrics

private long updateSizeMetrics(LruCachedBlock cb,
 boolean evict)

Helper function that updates the local size counter and also updates any per-cf or per-blocktype metrics it can discern from given LruCachedBlock

getBlock

public Cacheable getBlock(BlockCacheKey cacheKey,
 boolean caching,
 boolean repeat,
 boolean updateCacheMetrics)

Get the buffer of the block with the specified name.

Specified by:

getBlock in interface BlockCache

Parameters:

cacheKey - block's cache key

caching - true if the caller caches blocks on cache misses

repeat - Whether this is a repeat lookup for the same block (used to avoid double counting cache misses when doing double-check locking)

updateCacheMetrics - Whether to update cache metrics or not

Returns:

buffer of specified cache key, or null if not in cache

containsBlock

public boolean containsBlock(BlockCacheKey cacheKey)

Whether the cache contains block with specified cacheKey

Specified by:

containsBlock in interface FirstLevelBlockCache

Parameters:

cacheKey - cache key for the block

Returns:

true if contains the block

evictBlock

public boolean evictBlock(BlockCacheKey cacheKey)

Description copied from interface: BlockCache

Evict block from cache.

Specified by:

evictBlock in interface BlockCache

Parameters:

cacheKey - Block to evict

Returns:

true if block existed and was evicted, false if not

evictBlocksByHfileName

public int evictBlocksByHfileName(String hfileName)

Evicts all blocks for a specific HFile. This is an expensive operation implemented as a linear-time search through all blocks in the cache. Ideally this should be a search in a log-access-time map.

This is used for evict-on-close to remove all blocks of a specific HFile.

Specified by:

evictBlocksByHfileName in interface BlockCache

Returns:

the number of blocks evicted

evictBlock

protected long evictBlock(LruCachedBlock block,
 boolean evictedByEvictionProcess)

Evict the block, and it will be cached by the victim handler if exists && block may be read again later

Parameters:

evictedByEvictionProcess - true if the given block is evicted by EvictionThread

Returns:

the heap size of evicted block

runEviction

private void runEviction()

Multi-threaded call to run the eviction process.

isEvictionInProgress

boolean isEvictionInProgress()

getOverhead

long getOverhead()

evict

long evict()

Eviction method. Evict items in order of use, allowing delete items which haven't been used for the longest amount of time.

Returns:

how many bytes were freed

toString

public String toString()

Overrides:

toString in class Object

getMaxSize

public long getMaxSize()

Get the maximum size of this cache.

Specified by:

getMaxSize in interface BlockCache

Returns:

max size in bytes

getCurrentSize

public long getCurrentSize()

Description copied from interface: BlockCache

Returns the occupied size of the block cache, in bytes.

Specified by:

getCurrentSize in interface BlockCache

Returns:

occupied space in cache, in bytes

getCurrentDataSize

public long getCurrentDataSize()

Description copied from interface: BlockCache

Returns the occupied size of data blocks, in bytes.

Specified by:

getCurrentDataSize in interface BlockCache

Returns:

occupied space in cache, in bytes

getFreeSize

public long getFreeSize()

Description copied from interface: BlockCache

Returns the free size of the block cache, in bytes.

Specified by:

getFreeSize in interface BlockCache

Returns:

free space in cache, in bytes

size

public long size()

Description copied from interface: BlockCache

Returns the total size of the block cache, in bytes.

Specified by:

size in interface BlockCache

Returns:

size of cache, in bytes

getBlockCount

public long getBlockCount()

Description copied from interface: BlockCache

Returns the number of blocks currently cached in the block cache.

Specified by:

getBlockCount in interface BlockCache

Returns:

number of blocks in the cache

getDataBlockCount

public long getDataBlockCount()

Description copied from interface: BlockCache

Returns the number of data blocks currently cached in the block cache.

Specified by:

getDataBlockCount in interface BlockCache

Returns:

number of blocks in the cache

getEvictionThread

LruAdaptiveBlockCache.EvictionThread getEvictionThread()

logStats

public void logStats()

getStats

public CacheStats getStats()

Get counter statistics for this cache.

Includes: total accesses, hits, misses, evicted blocks, and runs of the eviction processes.

Specified by:

getStats in interface BlockCache

heapSize

public long heapSize()

Description copied from interface: HeapSize

Return the approximate 'exclusive deep size' of implementing object. Includes count of payload and hosting object sizings.

Specified by:

heapSize in interface HeapSize

calculateOverhead

private static long calculateOverhead(long maxSize,
 long blockSize,
 int concurrency)

iterator

public Iterator<CachedBlock> iterator()

Description copied from interface: BlockCache

Returns Iterator over the blocks in the cache.

Specified by:

iterator in interface BlockCache

Specified by:

iterator in interface Iterable<CachedBlock>

acceptableSize

long acceptableSize()

minSize

private long minSize()

singleSize

private long singleSize()

multiSize

private long multiSize()

memorySize

private long memorySize()

shutdown

public void shutdown()

Description copied from interface: BlockCache

Shutdown the cache.

Specified by:

shutdown in interface BlockCache

clearCache

public void clearCache()

Clears the cache. Used in tests.

getEncodingCountsForTest

public Map<DataBlockEncoding,Integer> getEncodingCountsForTest()

getMapForTests

Map<BlockCacheKey,LruCachedBlock> getMapForTests()

getBlockCaches

public BlockCache[] getBlockCaches()

Description copied from interface: BlockCache

Returns The list of sub blockcaches that make up this one; returns null if no sub caches.

Specified by:

getBlockCaches in interface BlockCache