org.apache.hadoop.hbase.io.hfile.bucket

Class BucketCache

java.lang.Object

org.apache.hadoop.hbase.io.hfile.bucket.BucketCache

All Implemented Interfaces:

Iterable<CachedBlock>, HeapSize, BlockCache

@InterfaceAudience.Private
public class BucketCache
extends Object
implements BlockCache, HeapSize

BucketCache uses BucketAllocator to allocate/free blocks, and uses BucketCache#ramCache and BucketCache#backingMap in order to determine if a given element is in the cache. The bucket cache can use off-heap memory ByteBufferIOEngine or mmap ExclusiveMemoryMmapIOEngine or pmem SharedMemoryMmapIOEngine or local files FileIOEngine to store/read the block data.

Eviction is via a similar algorithm as used in LruBlockCache

BucketCache can be used as mainly a block cache (see CombinedBlockCache), combined with a BlockCache to decrease CMS GC and heap fragmentation.

It also can be used as a secondary cache (e.g. using a file on ssd/fusionio to store blocks) to enlarge cache space via a victim cache.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_ERROR_TOLERATION_DURATION

Constructor Summary

Constructors

Constructor and Description
BucketCache(String ioEngineName, long capacity, int blockSize, int[] bucketSizes, int writerThreadNum, int writerQLen, String persistencePath)
BucketCache(String ioEngineName, long capacity, int blockSize, int[] bucketSizes, int writerThreadNum, int writerQLen, String persistencePath, int ioErrorsTolerationDuration, org.apache.hadoop.conf.Configuration conf)

Method Summary

Modifier and Type	Method and Description
long	acceptableSize()
void	cacheBlock(BlockCacheKey cacheKey, Cacheable buf) Cache the block with the specified name and buffer.
void	cacheBlock(BlockCacheKey cacheKey, Cacheable cachedItem, boolean inMemory) Cache the block with the specified name and buffer.
void	cacheBlock(BlockCacheKey cacheKey, Cacheable cachedItem, boolean inMemory, boolean waitWhenCache) Cache the block with the specified name and buffer.
void	cacheBlockWithWait(BlockCacheKey cacheKey, Cacheable cachedItem, boolean inMemory, boolean wait) Cache the block to ramCache
protected void	cacheBlockWithWaitInternal(BlockCacheKey cacheKey, Cacheable cachedItem, boolean inMemory, boolean wait)
boolean	evictBlock(BlockCacheKey cacheKey) Try to evict the block from BlockCache by force.
boolean	evictBlockIfNoRpcReferenced(BlockCacheKey blockCacheKey) NOTE: This method is only for test.
int	evictBlocksByHfileName(String hfileName) Evicts all blocks for a specific HFile.
protected String	getAlgorithm()
BucketAllocator	getAllocator()
Cacheable	getBlock(BlockCacheKey key, boolean caching, boolean repeat, boolean updateCacheMetrics) Get the buffer of the block with the specified key.
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.
String	getIoEngine()
long	getMaxSize() Returns the Max size of the block cache, in bytes.
long	getRealCacheSize()
int	getRpcRefCount(BlockCacheKey cacheKey)
CacheStats	getStats() Get the statistics for this block cache.
long	heapSize()
Iterator<CachedBlock>	iterator() Returns Iterator over the blocks in the cache.
void	logStats()
protected void	putIntoBackingMap(BlockCacheKey key, org.apache.hadoop.hbase.io.hfile.bucket.BucketEntry bucketEntry) Put the new bucket entry into backingMap.
protected boolean	removeFromRamCache(BlockCacheKey cacheKey)
protected boolean	shouldReplaceExistingCacheBlock(BlockCacheKey cacheKey, Cacheable newBlock)
void	shutdown() Shutdown the cache.
long	size() Returns the total size of the block cache, in bytes.
protected void	startWriterThreads() Called by the constructor to start the writer threads.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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

DEFAULT_ERROR_TOLERATION_DURATION

public static final int DEFAULT_ERROR_TOLERATION_DURATION

See Also:

Constant Field Values

Constructor Detail

BucketCache

public BucketCache(String ioEngineName,
                   long capacity,
                   int blockSize,
                   int[] bucketSizes,
                   int writerThreadNum,
                   int writerQLen,
                   String persistencePath)
            throws IOException

Throws:

IOException

BucketCache

public BucketCache(String ioEngineName,
                   long capacity,
                   int blockSize,
                   int[] bucketSizes,
                   int writerThreadNum,
                   int writerQLen,
                   String persistencePath,
                   int ioErrorsTolerationDuration,
                   org.apache.hadoop.conf.Configuration conf)
            throws IOException

Throws:

IOException

Method Detail

startWriterThreads

protected void startWriterThreads()

Called by the constructor to start the writer threads. Used by tests that need to override starting the threads.

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

getIoEngine

public String getIoEngine()

cacheBlock

public void cacheBlock(BlockCacheKey cacheKey,
                       Cacheable buf)

Cache the block with the specified name and buffer.

Specified by:

cacheBlock in interface BlockCache

Parameters:

cacheKey - block's cache key

buf - block buffer

cacheBlock

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

Cache the block with the specified name and buffer.

Specified by:

cacheBlock in interface BlockCache

Parameters:

cacheKey - block's cache key

cachedItem - block buffer

inMemory - if block is in-memory

cacheBlock

public void cacheBlock(BlockCacheKey cacheKey,
                       Cacheable cachedItem,
                       boolean inMemory,
                       boolean waitWhenCache)

Cache the block with the specified name and buffer.

Specified by:

cacheBlock in interface BlockCache

Parameters:

cacheKey - block's cache key

cachedItem - block buffer

inMemory - if block is in-memory

waitWhenCache - Whether to wait for the cache to be flushed mainly when BucketCache is configured.

cacheBlockWithWait

public void cacheBlockWithWait(BlockCacheKey cacheKey,
                               Cacheable cachedItem,
                               boolean inMemory,
                               boolean wait)

Cache the block to ramCache

Parameters:

cacheKey - block's cache key

cachedItem - block buffer

inMemory - if block is in-memory

wait - if true, blocking wait when queue is full

shouldReplaceExistingCacheBlock

protected boolean shouldReplaceExistingCacheBlock(BlockCacheKey cacheKey,
                                                  Cacheable newBlock)

cacheBlockWithWaitInternal

protected void cacheBlockWithWaitInternal(BlockCacheKey cacheKey,
                                          Cacheable cachedItem,
                                          boolean inMemory,
                                          boolean wait)

getBlock

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

Get the buffer of the block with the specified key.

Specified by:

getBlock in interface BlockCache

Parameters:

key - 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

updateCacheMetrics - Whether we should update cache metrics or not

Returns:

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

evictBlock

public boolean evictBlock(BlockCacheKey cacheKey)

Try to evict the block from BlockCache by force. We'll call this in few cases:
1. Close an HFile, and clear all cached blocks.
2. Call Admin.clearBlockCache(TableName) to clear all blocks for a given table.

Firstly, we'll try to remove the block from RAMCache,and then try to evict from backingMap. Here we evict the block from backingMap immediately, but only free the reference from bucket cache by calling BucketEntry.markedAsEvicted. If there're still some RPC referring this block, block can only be de-allocated when all of them release the block.

NOTICE: we need to grab the write offset lock firstly before releasing the reference from bucket cache. if we don't, we may read an BucketEntry with refCnt = 0 when getBlock(BlockCacheKey, boolean, boolean, boolean), it's a memory leak.

Specified by:

evictBlock in interface BlockCache

Parameters:

cacheKey - Block to evict

Returns:

true to indicate whether we've evicted successfully or not.

evictBlockIfNoRpcReferenced

public boolean evictBlockIfNoRpcReferenced(BlockCacheKey blockCacheKey)

NOTE: This method is only for test.

removeFromRamCache

protected boolean removeFromRamCache(BlockCacheKey cacheKey)

logStats

public void logStats()

getRealCacheSize

public long getRealCacheSize()

acceptableSize

public long acceptableSize()

putIntoBackingMap

protected void putIntoBackingMap(BlockCacheKey key,
                                 org.apache.hadoop.hbase.io.hfile.bucket.BucketEntry bucketEntry)

Put the new bucket entry into backingMap. Notice that we are allowed to replace the existing cache with a new block for the same cache key. there's a corner case: one thread cache a block in ramCache, copy to io-engine and add a bucket entry to backingMap. Caching another new block with the same cache key do the same thing for the same cache key, so if not evict the previous bucket entry, then memory leak happen because the previous bucketEntry is gone but the bucketAllocator do not free its memory.

Parameters:

key - Block cache key

bucketEntry - Bucket entry to put into backingMap.

See Also:

BlockCacheUtil.shouldReplaceExistingCacheBlock(BlockCache blockCache,BlockCacheKey cacheKey, Cacheable newBlock)

shutdown

public void shutdown()

Description copied from interface: BlockCache

Shutdown the cache.

Specified by:

shutdown in interface BlockCache

getStats

public CacheStats getStats()

Description copied from interface: BlockCache

Get the statistics for this block cache.

Specified by:

getStats in interface BlockCache

getAllocator

public BucketAllocator getAllocator()

heapSize

public long heapSize()

Specified by:

heapSize in interface HeapSize

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

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

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

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

getAlgorithm

protected String getAlgorithm()

evictBlocksByHfileName

public int evictBlocksByHfileName(String hfileName)

Evicts all blocks for a specific HFile.

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

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

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

getRpcRefCount

public int getRpcRefCount(BlockCacheKey cacheKey)