TinyLfuBlockCache (Apache HBase 2.5.0 API)

java.lang.Object
- org.apache.hadoop.hbase.io.hfile.TinyLfuBlockCache

All Implemented Interfaces:

Iterable<CachedBlock>, HeapSize, BlockCache, FirstLevelBlockCache, ResizableBlockCache
```
@InterfaceAudience.Private
public final class TinyLfuBlockCache
extends Object
implements FirstLevelBlockCache
```
A block cache that is memory-aware using HeapSize, memory bounded using the W-TinyLFU eviction algorithm, and concurrent. This implementation delegates to a Caffeine cache to provide O(1) read and write operations.
- W-TinyLFU: http://arxiv.org/pdf/1512.00727.pdf
- Caffeine: https://github.com/ben-manes/caffeine
- Cache design: http://highscalability.com/blog/2016/1/25/design-of-a-modern-cache.html

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`TinyLfuBlockCache.CachedBlockView`
`private class`	`TinyLfuBlockCache.EvictionListener` A removal listener to asynchronously record evictions and populate the victim cache.

Field Summary

Fields
Modifier and Type	Field and Description
`(package private) com.github.benmanes.caffeine.cache.Cache<BlockCacheKey,Cacheable>`	`cache`
`private static long`	`DEFAULT_MAX_BLOCK_SIZE`
`private static org.slf4j.Logger`	`LOG`
`private static String`	`MAX_BLOCK_SIZE`
`private long`	`maxBlockSize`
`private com.github.benmanes.caffeine.cache.Policy.Eviction<BlockCacheKey,Cacheable>`	`policy`
`private static int`	`STAT_THREAD_PERIOD_SECONDS`
`private CacheStats`	`stats`
`private ScheduledExecutorService`	`statsThreadPool`
`private BlockCache`	`victimCache`

Constructor Summary

Constructors
Constructor and Description
`TinyLfuBlockCache(long maximumSizeInBytes, long avgBlockSize, Executor executor, org.apache.hadoop.conf.Configuration conf)` Creates a block cache.
`TinyLfuBlockCache(long maximumSizeInBytes, long avgBlockSize, long maxBlockSize, Executor executor)` Creates a block cache.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`private Cacheable`	`asReferencedHeapBlock(Cacheable buf)` The block cached in TinyLfuBlockCache 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.
`void`	`cacheBlock(BlockCacheKey key, Cacheable value)` Add block to cache (defaults to not in-memory).
`void`	`cacheBlock(BlockCacheKey cacheKey, Cacheable value, boolean inMemory)` Add block to cache.
`boolean`	`containsBlock(BlockCacheKey cacheKey)` Whether the cache contains the block with specified cacheKey
`boolean`	`evictBlock(BlockCacheKey cacheKey)` Evict block from cache.
`int`	`evictBlocksByHfileName(String hfileName)` Evicts all blocks for the given HFile.
`Cacheable`	`getBlock(BlockCacheKey cacheKey, boolean caching, boolean repeat, boolean updateCacheMetrics)` Fetch block from cache.
`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.
`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.
`long`	`getFreeSize()` Returns the free size of the block cache, in bytes.
`long`	`getMaxSize()` Returns the Max size of the block cache, in bytes.
`CacheStats`	`getStats()` Get the statistics for this block cache.
`long`	`heapSize()` Return the approximate 'exclusive deep size' of implementing object.
`Iterator<CachedBlock>`	`iterator()` Returns Iterator over the blocks in the cache.
`private void`	`logStats()`
`private void`	`recordEviction()` Records an eviction.
`void`	`setMaxSize(long size)` 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.
`long`	`size()` Returns the total size of the block cache, in bytes.
`String`	`toString()`

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
isMetaBlock

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Field Detail
  - LOG
```
private static final org.slf4j.Logger LOG
```
  - MAX_BLOCK_SIZE
```
private static final String 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
  - STAT_THREAD_PERIOD_SECONDS
```
private static final int STAT_THREAD_PERIOD_SECONDS
```
    See Also:
    
    Constant Field Values
  - policy
```
private final transient com.github.benmanes.caffeine.cache.Policy.Eviction<BlockCacheKey,Cacheable> policy
```
  - statsThreadPool
```
private final transient ScheduledExecutorService statsThreadPool
```
  - maxBlockSize
```
private final long maxBlockSize
```
  - stats
```
private final CacheStats stats
```
  - victimCache
```
private transient BlockCache victimCache
```
  - cache
```
final transient com.github.benmanes.caffeine.cache.Cache<BlockCacheKey,Cacheable> cache
```
- Constructor Detail
  - TinyLfuBlockCache
```
public TinyLfuBlockCache(long maximumSizeInBytes,
                         long avgBlockSize,
                         Executor executor,
                         org.apache.hadoop.conf.Configuration conf)
```
    Creates a block cache.
    
    Parameters:
    
    maximumSizeInBytes - maximum size of this cache, in bytes
    
    avgBlockSize - expected average size of blocks, in bytes
    
    executor - the cache's executor
    
    conf - additional configuration
  - TinyLfuBlockCache
```
public TinyLfuBlockCache(long maximumSizeInBytes,
                         long avgBlockSize,
                         long maxBlockSize,
                         Executor executor)
```
    Creates a block cache.
    
    Parameters:
    
    maximumSizeInBytes - maximum size of this cache, in bytes
    
    avgBlockSize - expected average size of blocks, in bytes
    
    maxBlockSize - maximum size of a block, in bytes
    
    executor - the cache's executor
- Method Detail
  - 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
  - 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
  - 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
  - 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
  - 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
  - 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
  - setMaxSize
```
public void setMaxSize(long size)
```
    Description copied from interface: ResizableBlockCache
    
    Sets the max heap size that can be used by the BlockCache.
    
    Specified by:
    
    setMaxSize in interface ResizableBlockCache
    
    Parameters:
    
    size - The max heap size.
  - containsBlock
```
public boolean containsBlock(BlockCacheKey cacheKey)
```
    Description copied from interface: FirstLevelBlockCache
    
    Whether the cache contains the block with specified cacheKey
    
    Specified by:
    
    containsBlock in interface FirstLevelBlockCache
    
    Parameters:
    
    cacheKey - cache key for the block
    
    Returns:
    
    true if it contains the block
  - getBlock
```
public Cacheable getBlock(BlockCacheKey cacheKey,
                          boolean caching,
                          boolean repeat,
                          boolean updateCacheMetrics)
```
    Description copied from interface: BlockCache
    
    Fetch block from cache.
    
    Specified by:
    
    getBlock in interface BlockCache
    
    Parameters:
    
    cacheKey - Block to fetch.
    
    caching - Whether this request has caching enabled (used for stats)
    
    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:
    
    Block or null if block is not in 2 cache.
  - cacheBlock
```
public void cacheBlock(BlockCacheKey cacheKey,
                       Cacheable value,
                       boolean inMemory)
```
    Description copied from interface: BlockCache
    
    Add block to cache.
    
    Specified by:
    
    cacheBlock in interface BlockCache
    
    Parameters:
    
    cacheKey - The block's cache key.
    
    value - The block contents wrapped in a ByteBuffer.
    
    inMemory - Whether block should be treated as in-memory
  - cacheBlock
```
public void cacheBlock(BlockCacheKey key,
                       Cacheable value)
```
    Description copied from interface: BlockCache
    
    Add block to cache (defaults to not in-memory).
    
    Specified by:
    
    cacheBlock in interface BlockCache
    
    Parameters:
    
    key - The block's cache key.
    
    value - The object to cache.
  - asReferencedHeapBlock
```
private Cacheable asReferencedHeapBlock(Cacheable buf)
```
    The block cached in TinyLfuBlockCache 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 TinyLfuBlockCache size is always calculated based on the total heap size, if caching an off-heap block in TinyLfuBlockCache, 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 TinyLfuBlockCache 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.
  - 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)
```
    Description copied from interface: BlockCache
    
    Evicts all blocks for the given HFile.
    
    Specified by:
    
    evictBlocksByHfileName in interface BlockCache
    
    Returns:
    
    the number of blocks evicted
  - getStats
```
public CacheStats getStats()
```
    Description copied from interface: BlockCache
    
    Get the statistics for this block cache. n
    
    Specified by:
    
    getStats in interface BlockCache
  - shutdown
```
public void shutdown()
```
    Description copied from interface: BlockCache
    
    Shutdown the cache.
    
    Specified by:
    
    shutdown in interface BlockCache
  - 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
  - iterator
```
public Iterator<CachedBlock> iterator()
```
    Description copied from interface: BlockCache
    
    Returns Iterator over the blocks in the cache.
    
    Specified by:
    
    iterator in interface Iterable<CachedBlock>
    
    Specified by:
    
    iterator in interface BlockCache
  - logStats
```
private void logStats()
```
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - recordEviction
```
private void recordEviction()
```
    Records an eviction. The number of eviction operations and evicted blocks are identical, as an eviction is triggered immediately when the capacity has been exceeded. An eviction is performed asynchronously. See the library's documentation for details on write buffers, batching, and maintenance behavior.
  - getMaxSize
```
public long getMaxSize()
```
    Description copied from interface: BlockCache
    
    Returns the Max size of the block cache, in bytes.
    
    Specified by:
    
    getMaxSize in interface BlockCache
    
    Returns:
    
    size of 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
  - 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

Class TinyLfuBlockCache

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

Field Detail

LOG

MAX_BLOCK_SIZE

DEFAULT_MAX_BLOCK_SIZE

STAT_THREAD_PERIOD_SECONDS

policy

statsThreadPool

maxBlockSize

stats

victimCache

cache

Constructor Detail

TinyLfuBlockCache

TinyLfuBlockCache

Method Detail

setVictimCache

size

getFreeSize

getCurrentSize

getBlockCount

heapSize

setMaxSize

containsBlock

getBlock

cacheBlock

cacheBlock

asReferencedHeapBlock

evictBlock

evictBlocksByHfileName

getStats

shutdown

getBlockCaches

iterator

logStats

toString

recordEviction

getMaxSize

getCurrentDataSize

getDataBlockCount