Package 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

@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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private class	BucketCache.BucketEntryGroup	Used to group bucket entries into priority buckets.
protected static enum	BucketCache.CacheState	Enum to represent the state of cache
(package private) static class	BucketCache.RAMCache	Wrapped the delegate ConcurrentMap with maintaining its block's reference count.
(package private) static class	BucketCache.RAMQueueEntry	Block Entry stored in the memory with key,data and so on
private static class	BucketCache.StatisticsThread
(package private) class	BucketCache.WriterThread

Field Summary

Fields

Modifier and Type	Field	Description
(package private) static final String	ACCEPT_FACTOR_CONFIG_NAME
private float	acceptableFactor	Acceptable size of cache (no evictions if size < acceptable)
private final AtomicLong	accessCount	Cache access count (sequential ID)
private String	algorithm	Use MessageDigest class's encryption algorithms to check persistent file integrity, default algorithm is MD5
private static final int	ALLOCATION_FAIL_LOG_TIME_PERIOD
private long	allocFailLogPrevTs
(package private) static final String	BACKING_MAP_PERSISTENCE_CHUNK_SIZE
(package private) Map<BlockCacheKey,BucketEntry>	backingMap
private AtomicBoolean	backingMapValidated
(package private) static final String	BLOCK_ORPHAN_GRACE_PERIOD	The cache age of blocks to check if the related file is present on any online regions.
(package private) static final long	BLOCK_ORPHAN_GRACE_PERIOD_DEFAULT
private final LongAdder	blockNumber	Current number of cached elements
(package private) NavigableSet<BlockCacheKey>	blocksByHFile
private final long	blockSize	Approximate block size
private BucketAllocator	bucketAllocator
private long	bucketcachePersistInterval
private final long	cacheCapacity
private BucketCachePersister	cachePersister
private BucketCache.CacheState	cacheState	Flag if the cache is enabled or not...
private final BucketCacheStats	cacheStats
private org.apache.hadoop.conf.Configuration	conf
private static final float	DEFAULT_ACCEPT_FACTOR
(package private) static final long	DEFAULT_BACKING_MAP_PERSISTENCE_CHUNK_SIZE
private static final int	DEFAULT_CACHE_WAIT_TIME
static final int	DEFAULT_ERROR_TOLERATION_DURATION
private static final float	DEFAULT_EXTRA_FREE_FACTOR
private static final String	DEFAULT_FILE_VERIFY_ALGORITHM
private static final int	DEFAULT_FREE_ENTIRE_BLOCK_FACTOR
(package private) static final float	DEFAULT_MEMORY_FACTOR
(package private) static final float	DEFAULT_MIN_FACTOR
(package private) static final float	DEFAULT_MULTI_FACTOR
private static final long	DEFAULT_QUEUE_ADDITION_WAIT_TIME
(package private) static final float	DEFAULT_SINGLE_FACTOR	Priority buckets
(package private) static final int	DEFAULT_WRITER_QUEUE_ITEMS
(package private) static final int	DEFAULT_WRITER_THREADS
(package private) static final String	EXTRA_FREE_FACTOR_CONFIG_NAME
private float	extraFreeFactor	Free this floating point factor of extra blocks when evicting.
private static final String	FILE_VERIFY_ALGORITHM
private boolean	freeInProgress	Volatile boolean to track if free space is in process or not
private final Lock	freeSpaceLock
(package private) final Map<String,Pair<String,Long>>	fullyCachedFiles	Map of hFile -> Region -> File size.
private final LongAdder	heapSize
(package private) final IOEngine	ioEngine
private long	ioErrorStartTime
private final int	ioErrorsTolerationDuration	Duration of IO errors tolerated before we disable cache, 1 min as default
(package private) static AtomicBoolean	isCacheInconsistent
private static final org.slf4j.Logger	LOG
(package private) static final String	MEMORY_FACTOR_CONFIG_NAME
private float	memoryFactor	In-memory bucket size
(package private) static final String	MIN_FACTOR_CONFIG_NAME
private float	minFactor	Minimum threshold of cache (when evicting, evict until size < min)
(package private) static final String	MULTI_FACTOR_CONFIG_NAME
private float	multiFactor	Multiple access bucket size
(package private) final IdReadWriteLock<Long>	offsetLock	A ReentrantReadWriteLock to lock on a particular block identified by offset.
private Map<String,HRegion>	onlineRegions
private long	orphanBlockGracePeriod
private long	persistenceChunkSize
private final String	persistencePath
static final String	QUEUE_ADDITION_WAIT_TIME
private long	queueAdditionWaitTime
(package private) final BucketCache.RAMCache	ramCache
private final LongAdder	realCacheSize
(package private) final Map<String,Long>	regionCachedSize	Map of region -> total size of the region prefetched on this region server.
private final ScheduledExecutorService	scheduleThreadPool	Statistics thread schedule pool (for heavy debugging, could remove)
(package private) static final String	SINGLE_FACTOR_CONFIG_NAME	Priority buckets config
private float	singleFactor	Single access bucket size
private static final int	statThreadPeriod	Statistics thread
private static final boolean	STRONG_REF_DEFAULT
private static final String	STRONG_REF_KEY	Use strong reference for offsetLock or not
(package private) final ArrayList<BlockingQueue<BucketCache.RAMQueueEntry>>	writerQueues	A list of writer queues.
(package private) final BucketCache.WriterThread[]	writerThreads

Constructor Summary

Constructors

Constructor	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)
BucketCache(String ioEngineName, long capacity, int blockSize, int[] bucketSizes, int writerThreadNum, int writerQLen, String persistencePath, int ioErrorsTolerationDuration, org.apache.hadoop.conf.Configuration conf, Map<String,HRegion> onlineRegions)

Method Summary

Modifier and Type	Method	Description
long	acceptableSize()
(package private) void	blockEvicted(BlockCacheKey cacheKey, BucketEntry bucketEntry, boolean decrementBlockNumber, boolean evictedByEvictionProcess)	This method is invoked after the bucketEntry is removed from backingMap
Optional<Boolean>	blockFitsIntoTheCache(HFileBlock block)	Checks whether there's enough space left in the cache to accommodate the passed block.
private int	bucketSizesAboveThresholdCount(float minFactor)	Return the count of bucketSizeinfos still need free space
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)
private long	calculateBytesToFree(StringBuilder msgBuffer)
private void	checkIOErrorIsTolerated()	Check whether we tolerate IO error this time.
ByteBuffAllocator.Recycler	createRecycler(BucketEntry bucketEntry)	Create the ByteBuffAllocator.Recycler for BucketEntry.refCnt,which would be used as RefCnt.recycler of HFileBlock#buf returned from getBlock(org.apache.hadoop.hbase.io.hfile.BlockCacheKey, boolean, boolean, boolean).
private void	disableCache()	Used to shut down the cache -or- turn it off in the case of something broken.
(package private) void	doDrain(List<BucketCache.RAMQueueEntry> entries, ByteBuffer metaBuff)	Flush the entries in ramCache to IOEngine and add bucket entry to backingMap.
private boolean	doEvictBlock(BlockCacheKey cacheKey, BucketEntry bucketEntry, boolean evictedByEvictionProcess)	Evict the BlockCacheKey and BucketEntry from backingMap and ramCache.
private void	dumpPrefetchList()
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.
int	evictBlocksRangeByHfileName(String hfileName, long initOffset, long endOffset)	Evict all blocks for the given file name between the passed offset values.
(package private) boolean	evictBucketEntryIfNoRpcReferenced(BlockCacheKey blockCacheKey, BucketEntry bucketEntry)	Evict BlockCacheKey and its corresponding BucketEntry only if BucketEntry.isRpcRef() is false.
void	fileCacheCompleted(org.apache.hadoop.fs.Path filePath, long size)
private void	fileNotFullyCached(String hfileName)
protected void	finalize()	Needed mostly for UTs that might run in the same VM and create different BucketCache instances on different UT methods.
(package private) void	freeBucketEntry(BucketEntry bucketEntry)	Free the {BucketEntry actually,which could only be invoked when the BucketEntry.refCnt becoming 0.
private void	freeEntireBuckets(int completelyFreeBucketsNeeded)	This method will find the buckets that are minimally occupied and are not reference counted and will free them completely without any constraint on the access times of the elements, and as a process will completely free at most the number of buckets passed, sometimes it might not due to changing refCounts
(package private) void	freeSpace(String why)	Free the space if the used size reaches acceptableSize() or one size block couldn't be allocated.
(package private) float	getAcceptableFactor()
protected String	getAlgorithm()
private Set<BlockCacheKey>	getAllCacheKeysForFile(String hfileName, long init, long end)
private static String	getAllocationFailWarningMessage(BucketAllocatorException fle, BucketCache.RAMQueueEntry re)	Prepare and return a warning message for Bucket Allocator Exception
BucketAllocator	getAllocator()
Map<BlockCacheKey,BucketEntry>	getBackingMap()
AtomicBoolean	getBackingMapValidated()
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.
BucketEntry	getBlockForReference(BlockCacheKey key)	If the passed cache key relates to a reference (<hfile>.<parentEncRegion>), this method looks for the block from the referred file, in the cache.
Optional<Integer>	getBlockSize(BlockCacheKey key)	Returns an Optional containing the size of the block related to the passed key.
static Optional<BucketCache>	getBucketCacheFromCacheConfig(CacheConfig cacheConf)
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.
(package private) float	getExtraFreeFactor()
long	getFreeSize()	Returns the free size of the block cache, in bytes.
Optional<Map<String,Pair<String,Long>>>	getFullyCachedFiles()	Returns an Optional containing the map of files that have been fully cached (all its blocks are present in the cache.
String	getIoEngine()
private IOEngine	getIOEngineFromName(String ioEngineName, long capacity, String persistencePath)	Get the IOEngine from the IO engine name
long	getMaxSize()	Returns the Max size of the block cache, in bytes.
(package private) float	getMemoryFactor()
(package private) float	getMinFactor()
(package private) float	getMultiFactor()
(package private) long	getPartitionSize(float partitionFactor)
String	getPersistencePath()
(package private) static List<BucketCache.RAMQueueEntry>	getRAMQueueEntries(BlockingQueue<BucketCache.RAMQueueEntry> q, List<BucketCache.RAMQueueEntry> receptacle)	Blocks until elements available in q then tries to grab as many as possible before returning.
long	getRealCacheSize()
Optional<Map<String,Long>>	getRegionCachedInfo()	Returns an Optional containing a map of regions and the percentage of how much of it has been cached so far.
int	getRpcRefCount(BlockCacheKey cacheKey)
(package private) float	getSingleFactor()
CacheStats	getStats()	Get the statistics for this block cache.
long	heapSize()	Return the approximate 'exclusive deep size' of implementing object.
private void	instantiateWriterThreads()	Called by the constructor to instantiate the writer threads.
Optional<Boolean>	isAlreadyCached(BlockCacheKey key)	Checks whether the block for the passed key is already cached.
boolean	isCacheEnabled()	API to check whether or not, the cache is enabled.
boolean	isCacheInconsistent()
(package private) boolean	isCacheInitialized(String api)
boolean	isCachePersistenceEnabled()
boolean	isCachePersistent()
Iterator<CachedBlock>	iterator()	Returns Iterator over the blocks in the cache.
private void	join()
void	logStats()
void	notifyFileCachingCompleted(org.apache.hadoop.fs.Path fileName, int totalBlockCount, int dataBlockCount, long size)	Notifies the cache implementation that the given file has been fully cached (all its blocks made into the cache).
private void	parsePB(org.apache.hadoop.hbase.shaded.protobuf.generated.BucketCacheProtos.BucketCacheEntry proto)
private void	persistChunkedBackingMap(FileOutputStream fos)
(package private) void	persistToFile()
protected void	putIntoBackingMap(BlockCacheKey key, BucketEntry bucketEntry)	Put the new bucket entry into backingMap.
protected boolean	removeFromRamCache(BlockCacheKey cacheKey)
private void	retrieveChunkedBackingMap(FileInputStream in)
private void	retrieveFromFile(int[] bucketSizes)
private void	sanityCheckConfigs()
void	setCacheInconsistent(boolean setCacheInconsistent)
protected void	setCacheState(BucketCache.CacheState state)
Optional<Boolean>	shouldCacheFile(String fileName)	Checks whether blocks for the passed file should be cached or not.
protected boolean	shouldReplaceExistingCacheBlock(BlockCacheKey cacheKey, Cacheable newBlock)
void	shutdown()	Shutdown the cache.
long	size()	Returns the total size of the block cache, in bytes.
(package private) void	startBucketCachePersisterThread()
private void	startPersistenceRetriever(int[] bucketSizes, long capacity)
protected void	startWriterThreads()	Called by the constructor to start the writer threads.
(package private) void	stopWriterThreads()	Only used in test
private void	updateCacheIndex(org.apache.hadoop.hbase.shaded.protobuf.generated.BucketCacheProtos.BackingMap chunk, Map<Integer,String> deserializer)
private void	updateRegionCachedSize(org.apache.hadoop.fs.Path filePath, long cachedSize)
private void	updateRegionSizeMapWhileRetrievingFromFile()
private void	verifyCapacityAndClasses(long capacitySize, String ioclass, String mapclass)
private void	verifyFileIntegrity(org.apache.hadoop.hbase.shaded.protobuf.generated.BucketCacheProtos.BucketCacheEntry proto)
boolean	waitForCacheInitialization(long timeout)	Wait for the block cache implementation to be completely enabled.

Methods inherited from class java.lang.Object

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

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

getBlock, isMetaBlock

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Details

LOG

private static final org.slf4j.Logger LOG

SINGLE_FACTOR_CONFIG_NAME

static final String SINGLE_FACTOR_CONFIG_NAME

Priority buckets config

See Also:

• Constant Field Values

MULTI_FACTOR_CONFIG_NAME

static final String MULTI_FACTOR_CONFIG_NAME

See Also:

• Constant Field Values

MEMORY_FACTOR_CONFIG_NAME

static final String MEMORY_FACTOR_CONFIG_NAME

See Also:

• Constant Field Values

EXTRA_FREE_FACTOR_CONFIG_NAME

static final String EXTRA_FREE_FACTOR_CONFIG_NAME

See Also:

• Constant Field Values

ACCEPT_FACTOR_CONFIG_NAME

static final String ACCEPT_FACTOR_CONFIG_NAME

See Also:

• Constant Field Values

MIN_FACTOR_CONFIG_NAME

static final String MIN_FACTOR_CONFIG_NAME

See Also:

• Constant Field Values

BACKING_MAP_PERSISTENCE_CHUNK_SIZE

static final String BACKING_MAP_PERSISTENCE_CHUNK_SIZE

See Also:

• Constant Field Values

STRONG_REF_KEY

private static final String STRONG_REF_KEY

Use strong reference for offsetLock or not

See Also:

• Constant Field Values

STRONG_REF_DEFAULT

private static final boolean STRONG_REF_DEFAULT

See Also:

• Constant Field Values

BLOCK_ORPHAN_GRACE_PERIOD

static final String BLOCK_ORPHAN_GRACE_PERIOD

The cache age of blocks to check if the related file is present on any online regions.

See Also:

• Constant Field Values

BLOCK_ORPHAN_GRACE_PERIOD_DEFAULT

static final long BLOCK_ORPHAN_GRACE_PERIOD_DEFAULT

See Also:

• Constant Field Values

DEFAULT_SINGLE_FACTOR

static final float DEFAULT_SINGLE_FACTOR

Priority buckets

See Also:

• Constant Field Values

DEFAULT_MULTI_FACTOR

static final float DEFAULT_MULTI_FACTOR

See Also:

• Constant Field Values

DEFAULT_MEMORY_FACTOR

static final float DEFAULT_MEMORY_FACTOR

See Also:

• Constant Field Values

DEFAULT_MIN_FACTOR

static final float DEFAULT_MIN_FACTOR

See Also:

• Constant Field Values

DEFAULT_EXTRA_FREE_FACTOR

private static final float DEFAULT_EXTRA_FREE_FACTOR

See Also:

• Constant Field Values

DEFAULT_ACCEPT_FACTOR

private static final float DEFAULT_ACCEPT_FACTOR

See Also:

• Constant Field Values

DEFAULT_FREE_ENTIRE_BLOCK_FACTOR

private static final int DEFAULT_FREE_ENTIRE_BLOCK_FACTOR

See Also:

• Constant Field Values

statThreadPeriod

private static final int statThreadPeriod

Statistics thread

See Also:

• Constant Field Values

DEFAULT_WRITER_THREADS

static final int DEFAULT_WRITER_THREADS

See Also:

• Constant Field Values

DEFAULT_WRITER_QUEUE_ITEMS

static final int DEFAULT_WRITER_QUEUE_ITEMS

See Also:

• Constant Field Values

DEFAULT_BACKING_MAP_PERSISTENCE_CHUNK_SIZE

static final long DEFAULT_BACKING_MAP_PERSISTENCE_CHUNK_SIZE

See Also:

• Constant Field Values

ioEngine

final transient IOEngine ioEngine

ramCache

final transient BucketCache.RAMCache ramCache

backingMap

transient Map<BlockCacheKey,BucketEntry> backingMap

backingMapValidated

private AtomicBoolean backingMapValidated

fullyCachedFiles

final Map<String,Pair<String,Long>> fullyCachedFiles

Map of hFile -> Region -> File size. This map is used to track all files completed prefetch, together with the region those belong to and the total cached size for the region.TestBlockEvictionOnRegionMovement

regionCachedSize

final Map<String,Long> regionCachedSize

Map of region -> total size of the region prefetched on this region server. This is the total size of hFiles for this region prefetched on this region server

cachePersister

private BucketCachePersister cachePersister

cacheState

private volatile BucketCache.CacheState cacheState

Flag if the cache is enabled or not... We shut it off if there are IO errors for some time, so that Bucket IO exceptions/errors don't bring down the HBase server.

writerQueues

final transient ArrayList<BlockingQueue<BucketCache.RAMQueueEntry>> writerQueues

A list of writer queues. We have a queue per BucketCache.WriterThread we have running. In other words, the work adding blocks to the BucketCache is divided up amongst the running WriterThreads. Its done by taking hash of the cache key modulo queue count. WriterThread when it runs takes whatever has been recently added and 'drains' the entries to the BucketCache. It then updates the ramCache and backingMap accordingly.

writerThreads

final transient BucketCache.WriterThread[] writerThreads

freeInProgress

private volatile boolean freeInProgress

Volatile boolean to track if free space is in process or not

freeSpaceLock

private final transient Lock freeSpaceLock

realCacheSize

private final LongAdder realCacheSize

heapSize

private final LongAdder heapSize

blockNumber

private final LongAdder blockNumber

Current number of cached elements

accessCount

private final AtomicLong accessCount

Cache access count (sequential ID)

DEFAULT_CACHE_WAIT_TIME

private static final int DEFAULT_CACHE_WAIT_TIME

See Also:

• Constant Field Values

cacheStats

private final BucketCacheStats cacheStats

persistencePath

private final String persistencePath

isCacheInconsistent

static AtomicBoolean isCacheInconsistent

cacheCapacity

private final long cacheCapacity

blockSize

private final long blockSize

Approximate block size

ioErrorsTolerationDuration

private final int ioErrorsTolerationDuration

Duration of IO errors tolerated before we disable cache, 1 min as default

DEFAULT_ERROR_TOLERATION_DURATION

public static final int DEFAULT_ERROR_TOLERATION_DURATION

See Also:

• Constant Field Values

ioErrorStartTime

private volatile long ioErrorStartTime

conf

private org.apache.hadoop.conf.Configuration conf

offsetLock

final transient IdReadWriteLock<Long> offsetLock

A ReentrantReadWriteLock to lock on a particular block identified by offset. The purpose of this is to avoid freeing the block which is being read.

blocksByHFile

NavigableSet<BlockCacheKey> blocksByHFile

scheduleThreadPool

private final transient ScheduledExecutorService scheduleThreadPool

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

bucketAllocator

private transient BucketAllocator bucketAllocator

acceptableFactor

private float acceptableFactor

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

minFactor

private float minFactor

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

extraFreeFactor

private float extraFreeFactor

Free this floating point factor of extra blocks when evicting. For example free the number of blocks requested * (1 + extraFreeFactor)

singleFactor

private float singleFactor

Single access bucket size

multiFactor

private float multiFactor

Multiple access bucket size

memoryFactor

private float memoryFactor

In-memory bucket size

bucketcachePersistInterval

private long bucketcachePersistInterval

FILE_VERIFY_ALGORITHM

private static final String FILE_VERIFY_ALGORITHM

See Also:

• Constant Field Values

DEFAULT_FILE_VERIFY_ALGORITHM

private static final String DEFAULT_FILE_VERIFY_ALGORITHM

See Also:

• Constant Field Values

QUEUE_ADDITION_WAIT_TIME

public static final String QUEUE_ADDITION_WAIT_TIME

See Also:

• Constant Field Values

DEFAULT_QUEUE_ADDITION_WAIT_TIME

private static final long DEFAULT_QUEUE_ADDITION_WAIT_TIME

See Also:

• Constant Field Values

queueAdditionWaitTime

private long queueAdditionWaitTime

algorithm

private String algorithm

Use MessageDigest class's encryption algorithms to check persistent file integrity, default algorithm is MD5

persistenceChunkSize

private long persistenceChunkSize

allocFailLogPrevTs

private long allocFailLogPrevTs

ALLOCATION_FAIL_LOG_TIME_PERIOD

private static final int ALLOCATION_FAIL_LOG_TIME_PERIOD

See Also:

• Constant Field Values

onlineRegions

private Map<String,HRegion> onlineRegions

orphanBlockGracePeriod

private long orphanBlockGracePeriod

Constructor Details

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

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,
 Map<String,HRegion> onlineRegions)
            throws IOException

Throws:

IOException

Method Details

startPersistenceRetriever

private void startPersistenceRetriever(int[] bucketSizes,
 long capacity)

sanityCheckConfigs

private void sanityCheckConfigs()

instantiateWriterThreads

private void instantiateWriterThreads()

Called by the constructor to instantiate the writer threads.

startWriterThreads

protected void startWriterThreads()

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

startBucketCachePersisterThread

void startBucketCachePersisterThread()

isCacheEnabled

public boolean isCacheEnabled()

Description copied from interface: BlockCache

API to check whether or not, the cache is enabled.

Specified by:

isCacheEnabled in interface BlockCache

Returns:

returns true if the cache is enabled, false otherwise.

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()

getIOEngineFromName

private IOEngine getIOEngineFromName(String ioEngineName,
 long capacity,
 String persistencePath)
                              throws IOException

Get the IOEngine from the IO engine name

Returns:

the IOEngine

Throws:

IOException

isCachePersistenceEnabled

public boolean isCachePersistenceEnabled()

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)

getBlockForReference

public BucketEntry getBlockForReference(BlockCacheKey key)

If the passed cache key relates to a reference (<hfile>.<parentEncRegion>), this method looks for the block from the referred file, in the cache. If present in the cache, the block for the referred file is returned, otherwise, this method returns null. It will also return null if the passed cache key doesn't relate to a reference.

Parameters:

key - the BlockCacheKey instance to look for in the cache.

Returns:

the cached block from the referred file, null if there's no such block in the cache or the passed key doesn't relate to a reference.

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

blockEvicted

void blockEvicted(BlockCacheKey cacheKey,
 BucketEntry bucketEntry,
 boolean decrementBlockNumber,
 boolean evictedByEvictionProcess)

This method is invoked after the bucketEntry is removed from backingMap

fileNotFullyCached

private void fileNotFullyCached(String hfileName)

fileCacheCompleted

public void fileCacheCompleted(org.apache.hadoop.fs.Path filePath,
 long size)

updateRegionCachedSize

private void updateRegionCachedSize(org.apache.hadoop.fs.Path filePath,
 long cachedSize)

freeBucketEntry

void freeBucketEntry(BucketEntry bucketEntry)

Free the {BucketEntry actually,which could only be invoked when the BucketEntry.refCnt becoming 0.

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.

doEvictBlock

private boolean doEvictBlock(BlockCacheKey cacheKey,
 BucketEntry bucketEntry,
 boolean evictedByEvictionProcess)

Evict the BlockCacheKey and BucketEntry from backingMap and ramCache.
NOTE:When Evict from backingMap,only the matched BlockCacheKey and BucketEntry could be removed.

Parameters:

cacheKey - BlockCacheKey to evict.

bucketEntry - BucketEntry matched BlockCacheKey to evict.

Returns:

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

createRecycler

public ByteBuffAllocator.Recycler createRecycler(BucketEntry bucketEntry)

 Create the ByteBuffAllocator.Recycler for BucketEntry.refCnt,which would be used as
 RefCnt.recycler of HFileBlock#buf returned from getBlock(org.apache.hadoop.hbase.io.hfile.BlockCacheKey, boolean, boolean, boolean).
 NOTE: for getBlock(org.apache.hadoop.hbase.io.hfile.BlockCacheKey, boolean, boolean, boolean),the RefCnt.recycler of HFileBlock#buf
 from backingMap and ramCache are different:
 1.For RefCnt.recycler of HFileBlock#buf from backingMap,
   it is the return value of current createRecycler(org.apache.hadoop.hbase.io.hfile.bucket.BucketEntry) method.

 2.For RefCnt.recycler of HFileBlock#buf from ramCache,
   it is ByteBuffAllocator.putbackBuffer(java.nio.ByteBuffer).
 

evictBlockIfNoRpcReferenced

public boolean evictBlockIfNoRpcReferenced(BlockCacheKey blockCacheKey)

NOTE: This method is only for test.

evictBucketEntryIfNoRpcReferenced

boolean evictBucketEntryIfNoRpcReferenced(BlockCacheKey blockCacheKey,
 BucketEntry bucketEntry)

Evict BlockCacheKey and its corresponding BucketEntry only if BucketEntry.isRpcRef() is false.
NOTE:When evict from backingMap,only the matched BlockCacheKey and BucketEntry could be removed.

Parameters:

blockCacheKey - BlockCacheKey to evict.

bucketEntry - BucketEntry matched BlockCacheKey to evict.

Returns:

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

removeFromRamCache

protected boolean removeFromRamCache(BlockCacheKey cacheKey)

isCacheInconsistent

public boolean isCacheInconsistent()

setCacheInconsistent

public void setCacheInconsistent(boolean setCacheInconsistent)

setCacheState

protected void setCacheState(BucketCache.CacheState state)

logStats

public void logStats()

getRealCacheSize

public long getRealCacheSize()

acceptableSize

public long acceptableSize()

getPartitionSize

long getPartitionSize(float partitionFactor)

bucketSizesAboveThresholdCount

private int bucketSizesAboveThresholdCount(float minFactor)

Return the count of bucketSizeinfos still need free space

freeEntireBuckets

private void freeEntireBuckets(int completelyFreeBucketsNeeded)

This method will find the buckets that are minimally occupied and are not reference counted and will free them completely without any constraint on the access times of the elements, and as a process will completely free at most the number of buckets passed, sometimes it might not due to changing refCounts

Parameters:

completelyFreeBucketsNeeded - number of buckets to free

calculateBytesToFree

private long calculateBytesToFree(StringBuilder msgBuffer)

freeSpace

void freeSpace(String why)

Free the space if the used size reaches acceptableSize() or one size block couldn't be allocated. When freeing the space, we use the LRU algorithm and ensure there must be some blocks evicted

Parameters:

why - Why we are being called

putIntoBackingMap

protected void putIntoBackingMap(BlockCacheKey key,
 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)

getAllocationFailWarningMessage

private static String getAllocationFailWarningMessage(BucketAllocatorException fle,
 BucketCache.RAMQueueEntry re)

Prepare and return a warning message for Bucket Allocator Exception

Parameters:

fle - The exception

re - The RAMQueueEntry for which the exception was thrown.

Returns:

A warning message created from the input RAMQueueEntry object.

doDrain

void doDrain(List<BucketCache.RAMQueueEntry> entries,
 ByteBuffer metaBuff)
      throws InterruptedException

Flush the entries in ramCache to IOEngine and add bucket entry to backingMap. Process all that are passed in even if failure being sure to remove from ramCache else we'll never undo the references and we'll OOME.

Parameters:

entries - Presumes list passed in here will be processed by this invocation only. No interference expected.

Throws:

InterruptedException

getRAMQueueEntries

static List<BucketCache.RAMQueueEntry> getRAMQueueEntries(BlockingQueue<BucketCache.RAMQueueEntry> q,
 List<BucketCache.RAMQueueEntry> receptacle)
                                                   throws InterruptedException

Blocks until elements available in q then tries to grab as many as possible before returning.

Parameters:

receptacle - Where to stash the elements taken from queue. We clear before we use it just in case.

q - The queue to take from.

Returns:

receptacle laden with elements taken from the queue or empty if none found.

Throws:

InterruptedException

persistToFile

void persistToFile()
            throws IOException

Throws:

IOException

See Also:

• retrieveFromFile(int[])

isCachePersistent

public boolean isCachePersistent()

getRegionCachedInfo

public Optional<Map<String,Long>> getRegionCachedInfo()

Description copied from interface: BlockCache

Returns an Optional containing a map of regions and the percentage of how much of it has been cached so far.

Specified by:

getRegionCachedInfo in interface BlockCache

Returns:

empty optional if this method is not supported, otherwise the returned optional contains a map of current regions caching percentage.

retrieveFromFile

private void retrieveFromFile(int[] bucketSizes)
                       throws IOException

Throws:

IOException

See Also:

• persistToFile()

updateRegionSizeMapWhileRetrievingFromFile

private void updateRegionSizeMapWhileRetrievingFromFile()

dumpPrefetchList

private void dumpPrefetchList()

verifyCapacityAndClasses

private void verifyCapacityAndClasses(long capacitySize,
 String ioclass,
 String mapclass)
                               throws IOException

Throws:

IOException

verifyFileIntegrity

private void verifyFileIntegrity(org.apache.hadoop.hbase.shaded.protobuf.generated.BucketCacheProtos.BucketCacheEntry proto)

updateCacheIndex

private void updateCacheIndex(org.apache.hadoop.hbase.shaded.protobuf.generated.BucketCacheProtos.BackingMap chunk,
 Map<Integer,String> deserializer)
                       throws IOException

Throws:

IOException

parsePB

private void parsePB(org.apache.hadoop.hbase.shaded.protobuf.generated.BucketCacheProtos.BucketCacheEntry proto)
              throws IOException

Throws:

IOException

persistChunkedBackingMap

private void persistChunkedBackingMap(FileOutputStream fos)
                               throws IOException

Throws:

IOException

retrieveChunkedBackingMap

private void retrieveChunkedBackingMap(FileInputStream in)
                                throws IOException

Throws:

IOException

checkIOErrorIsTolerated

private void checkIOErrorIsTolerated()

Check whether we tolerate IO error this time. If the duration of IOEngine throwing errors exceeds ioErrorsDurationTimeTolerated, we will disable the cache

disableCache

private void disableCache()

Used to shut down the cache -or- turn it off in the case of something broken.

join

private void join()
           throws InterruptedException

Throws:

InterruptedException

shutdown

public void shutdown()

Description copied from interface: BlockCache

Shutdown the cache.

Specified by:

shutdown in interface BlockCache

finalize

protected void finalize()

Needed mostly for UTs that might run in the same VM and create different BucketCache instances on different UT methods.

Overrides:

finalize in class Object

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()

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

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

evictBlocksRangeByHfileName

public int evictBlocksRangeByHfileName(String hfileName,
 long initOffset,
 long endOffset)

Description copied from interface: BlockCache

Evict all blocks for the given file name between the passed offset values.

Specified by:

evictBlocksRangeByHfileName in interface BlockCache

Parameters:

hfileName - The file for which blocks should be evicted.

initOffset - the initial offset for the range of blocks to be evicted.

endOffset - the end offset for the range of blocks to be evicted.

Returns:

number of blocks evicted.

getAllCacheKeysForFile

private Set<BlockCacheKey> getAllCacheKeysForFile(String hfileName,
 long init,
 long end)

stopWriterThreads

void stopWriterThreads()
                throws InterruptedException

Only used in test

Throws:

InterruptedException

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>

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)

getAcceptableFactor

float getAcceptableFactor()

getMinFactor

float getMinFactor()

getExtraFreeFactor

float getExtraFreeFactor()

getSingleFactor

float getSingleFactor()

getMultiFactor

float getMultiFactor()

getMemoryFactor

float getMemoryFactor()

getPersistencePath

public String getPersistencePath()

getBackingMap

public Map<BlockCacheKey,BucketEntry> getBackingMap()

getBackingMapValidated

public AtomicBoolean getBackingMapValidated()

getFullyCachedFiles

public Optional<Map<String,Pair<String,Long>>> getFullyCachedFiles()

Description copied from interface: BlockCache

Returns an Optional containing the map of files that have been fully cached (all its blocks are present in the cache. This method may not be overridden by all implementing classes. In such cases, the returned Optional will be empty.

Specified by:

getFullyCachedFiles in interface BlockCache

Returns:

empty optional if this method is not supported, otherwise the returned optional contains a map of all files that have been fully cached.

getBucketCacheFromCacheConfig

public static Optional<BucketCache> getBucketCacheFromCacheConfig(CacheConfig cacheConf)

notifyFileCachingCompleted

public void notifyFileCachingCompleted(org.apache.hadoop.fs.Path fileName,
 int totalBlockCount,
 int dataBlockCount,
 long size)

Description copied from interface: BlockCache

Notifies the cache implementation that the given file has been fully cached (all its blocks made into the cache).

Specified by:

notifyFileCachingCompleted in interface BlockCache

Parameters:

fileName - the file that has been completely cached.

totalBlockCount - the total of blocks cached for this file.

dataBlockCount - number of DATA block type cached.

size - the size, in bytes, cached.

blockFitsIntoTheCache

public Optional<Boolean> blockFitsIntoTheCache(HFileBlock block)

Description copied from interface: BlockCache

Checks whether there's enough space left in the cache to accommodate the passed block. This method may not be overridden by all implementing classes. In such cases, the returned Optional will be empty. For subclasses implementing this logic, the returned Optional would contain the boolean value reflecting if the passed block fits into the remaining cache space available.

Specified by:

blockFitsIntoTheCache in interface BlockCache

Parameters:

block - the block we want to check if fits into the cache.

Returns:

empty optional if this method is not supported, otherwise the returned optional contains the boolean value informing if the block fits into the cache available space.

shouldCacheFile

public Optional<Boolean> shouldCacheFile(String fileName)

Description copied from interface: BlockCache

Checks whether blocks for the passed file should be cached or not. This method may not be overridden by all implementing classes. In such cases, the returned Optional will be empty. For subclasses implementing this logic, the returned Optional would contain the boolean value reflecting if the passed file should indeed be cached.

Specified by:

shouldCacheFile in interface BlockCache

Parameters:

fileName - to check if it should be cached.

Returns:

empty optional if this method is not supported, otherwise the returned optional contains the boolean value informing if the file should be cached.

isAlreadyCached

public Optional<Boolean> isAlreadyCached(BlockCacheKey key)

Description copied from interface: BlockCache

Checks whether the block for the passed key is already cached. This method may not be overridden by all implementing classes. In such cases, the returned Optional will be empty. For subclasses implementing this logic, the returned Optional would contain the boolean value reflecting if the block for the passed key is already cached or not.

Specified by:

isAlreadyCached in interface BlockCache

Parameters:

key - for the block we want to check if it's already in the cache.

Returns:

empty optional if this method is not supported, otherwise the returned optional contains the boolean value informing if the block is already cached.

getBlockSize

public Optional<Integer> getBlockSize(BlockCacheKey key)

Description copied from interface: BlockCache

Returns an Optional containing the size of the block related to the passed key. If the block is not in the cache, returned optional will be empty. Also, this method may not be overridden by all implementing classes. In such cases, the returned Optional will be empty.

Specified by:

getBlockSize in interface BlockCache

Parameters:

key - for the block we want to check if it's already in the cache.

Returns:

empty optional if this method is not supported, otherwise the returned optional contains the boolean value informing if the block is already cached.

isCacheInitialized

boolean isCacheInitialized(String api)

waitForCacheInitialization

public boolean waitForCacheInitialization(long timeout)

Description copied from interface: BlockCache

Wait for the block cache implementation to be completely enabled. Some block cache implementations may take longer to initialise, and this initialisation may be asynchronous.

Specified by:

waitForCacheInitialization in interface BlockCache

Parameters:

timeout - time to wait for the cache to become enabled.

Returns:

boolean true if the cache is enabled, false otherwise.