BucketCache (Apache HBase 1.2.12 API)

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 ramCache and backingMap in order to determine if a given element is in the cache. The bucket cache can use on-heap or off-heap memory ByteBufferIOEngine or in a file 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 LruBlockCache 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 LruBlockCache.setVictimCache(org.apache.hadoop.hbase.io.hfile.BlockCache)

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`(package private) static class`	`BucketCache.BucketEntry` Item in cache.
`private class`	`BucketCache.BucketEntryGroup` Used to group bucket entries into priority buckets.
`(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 and Description
`private AtomicLong`	`accessCount` Cache access count (sequential ID)
`(package private) ConcurrentMap<BlockCacheKey,BucketCache.BucketEntry>`	`backingMap`
`private AtomicLong`	`blockNumber` Current number of cached elements
`private ConcurrentIndex<String,BlockCacheKey>`	`blocksByHFile`
`private long`	`blockSize` Approximate block size
`private BucketAllocator`	`bucketAllocator`
`private long`	`cacheCapacity`
`private boolean`	`cacheEnabled` Flag if the cache is enabled or not...
`private BucketCacheStats`	`cacheStats`
`private static float`	`DEFAULT_ACCEPT_FACTOR`
`private static int`	`DEFAULT_CACHE_WAIT_TIME`
`static int`	`DEFAULT_ERROR_TOLERATION_DURATION`
`private static float`	`DEFAULT_EXTRA_FREE_FACTOR`
`private static int`	`DEFAULT_FREE_ENTIRE_BLOCK_FACTOR`
`private static float`	`DEFAULT_MEMORY_FACTOR`
`private static float`	`DEFAULT_MIN_FACTOR`
`private static float`	`DEFAULT_MULTI_FACTOR`
`private static float`	`DEFAULT_SINGLE_FACTOR` Priority buckets
`(package private) static int`	`DEFAULT_WRITER_QUEUE_ITEMS`
`(package private) static int`	`DEFAULT_WRITER_THREADS`
`private UniqueIndexMap<Integer>`	`deserialiserMap`
`private boolean`	`freeInProgress` Volatile boolean to track if free space is in process or not
`private Lock`	`freeSpaceLock`
`private AtomicLong`	`heapSize`
`(package private) IOEngine`	`ioEngine`
`private long`	`ioErrorStartTime`
`private int`	`ioErrorsTolerationDuration` Duration of IO errors tolerated before we disable cache, 1 min as default
`private static org.apache.commons.logging.Log`	`LOG`
`(package private) IdReadWriteLock`	`offsetLock` A ReentrantReadWriteLock to lock on a particular block identified by offset.
`private String`	`persistencePath`
`(package private) ConcurrentMap<BlockCacheKey,BucketCache.RAMQueueEntry>`	`ramCache`
`private AtomicLong`	`realCacheSize`
`private ScheduledExecutorService`	`scheduleThreadPool` Statistics thread schedule pool (for heavy debugging, could remove)
`private static int`	`statThreadPeriod` Statistics thread
`(package private) boolean`	`wait_when_cache`
`(package private) ArrayList<BlockingQueue<BucketCache.RAMQueueEntry>>`	`writerQueues` A list of writer queues.
`(package private) BucketCache.WriterThread[]`	`writerThreads`

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

Method Summary

Methods
Modifier and Type	Method and Description
`private long`	`acceptableSize()`
`(package private) void`	`blockEvicted(BlockCacheKey cacheKey, BucketCache.BucketEntry bucketEntry, boolean decrementBlockNumber)`
`private int`	`bucketSizesAboveThresholdCount(float minFactor)` Return the count of bucketSizeinfos still needf ree space
`void`	`cacheBlock(BlockCacheKey cacheKey, Cacheable buf)` Cache the block with the specified name and buffer.
`void`	`cacheBlock(BlockCacheKey cacheKey, Cacheable cachedItem, boolean inMemory, boolean cacheDataInL1)` Cache the block with the specified name and buffer.
`void`	`cacheBlockWithWait(BlockCacheKey cacheKey, Cacheable cachedItem, boolean inMemory, boolean wait)` Cache the block to ramCache
`private void`	`checkIOErrorIsTolerated()` Check whether we tolerate IO error this time.
`private void`	`disableCache()` Used to shut down the cache -or- turn it off in the case of something broken.
`boolean`	`evictBlock(BlockCacheKey cacheKey)` Evict block from cache.
`int`	`evictBlocksByHfileName(String hfileName)` Evicts all blocks for a specific HFile.
`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
`private void`	`freeSpace(String why)` Free the space if the used size reaches acceptableSize() or one size block couldn't be allocated.
`BucketAllocator`	`getAllocator()`
`Cacheable`	`getBlock(BlockCacheKey key, boolean caching, boolean repeat, boolean updateCacheMetrics)` Get the buffer of the block with the specified key.
`BlockCache[]`	`getBlockCaches()`
`long`	`getBlockCount()` Returns the number of blocks currently cached in the block cache.
`long`	`getCurrentSize()` Returns the occupied size of the block cache, in bytes.
`long`	`getFreeSize()` Returns the free size of the block cache, in bytes.
`String`	`getIoEngine()`
`private IOEngine`	`getIOEngineFromName(String ioEngineName, long capacity)` Get the IOEngine from the IO engine name
`long`	`getMaxSize()`
`(package private) static List<BucketCache.RAMQueueEntry>`	`getRAMQueueEntries(BlockingQueue<BucketCache.RAMQueueEntry> q, List<BucketCache.RAMQueueEntry> receptical)` Blocks until elements available in `q` then tries to grab as many as possible before returning.
`long`	`getRealCacheSize()`
`CacheStats`	`getStats()` Get the statistics for this block cache.
`long`	`heapSize()`
`(package private) boolean`	`isCacheEnabled()`
`Iterator<CachedBlock>`	`iterator()`
`private void`	`join()`
`void`	`logStats()`
`private long`	`memorySize()`
`private long`	`multiSize()`
`private void`	`persistToFile()`
`private void`	`retrieveFromFile(int[] bucketSizes)`
`void`	`shutdown()` Shutdown the cache.
`private long`	`singleSize()`
`long`	`size()` Returns the total size of the block cache, in bytes.
`protected void`	`startWriterThreads()` Called by the constructor to start the writer threads.
`(package private) void`	`stopWriterThreads()` Only used in test

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - LOG
```
private static final org.apache.commons.logging.Log LOG
```
  - DEFAULT_SINGLE_FACTOR
```
private static final float DEFAULT_SINGLE_FACTOR
```
    Priority buckets
    
    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_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_MIN_FACTOR
```
private static final float DEFAULT_MIN_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
  - ioEngine
```
final IOEngine ioEngine
```
  - ramCache
```
final ConcurrentMap<BlockCacheKey,BucketCache.RAMQueueEntry> ramCache
```
  - backingMap
```
ConcurrentMap<BlockCacheKey,BucketCache.BucketEntry> backingMap
```
  - cacheEnabled
```
private volatile boolean cacheEnabled
```
    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 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 BucketCache.WriterThread[] writerThreads
```
  - freeInProgress
```
private volatile boolean freeInProgress
```
    Volatile boolean to track if free space is in process or not
  - freeSpaceLock
```
private final Lock freeSpaceLock
```
  - deserialiserMap
```
private UniqueIndexMap<Integer> deserialiserMap
```
  - realCacheSize
```
private final AtomicLong realCacheSize
```
  - heapSize
```
private final AtomicLong heapSize
```
  - blockNumber
```
private final AtomicLong 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
  - wait_when_cache
```
boolean wait_when_cache
```
  - cacheStats
```
private final BucketCacheStats cacheStats
```
  - persistencePath
```
private final String persistencePath
```
  - 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
```
  - offsetLock
```
final IdReadWriteLock 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
```
private final ConcurrentIndex<String,BlockCacheKey> blocksByHFile
```
  - scheduleThreadPool
```
private final ScheduledExecutorService scheduleThreadPool
```
    Statistics thread schedule pool (for heavy debugging, could remove)
  - bucketAllocator
```
private BucketAllocator bucketAllocator
```
- Constructor Detail
  - BucketCache
```
public BucketCache(String ioEngineName,
           long capacity,
           int blockSize,
           int[] bucketSizes,
           int writerThreadNum,
           int writerQLen,
           String persistencePath)
            throws FileNotFoundException,
                   IOException
```
    Throws:
    
    FileNotFoundException
    
    IOException
  - BucketCache
```
public BucketCache(String ioEngineName,
           long capacity,
           int blockSize,
           int[] bucketSizes,
           int writerThreadNum,
           int writerQLen,
           String persistencePath,
           int ioErrorsTolerationDuration)
            throws FileNotFoundException,
                   IOException
```
    Throws:
    
    FileNotFoundException
    
    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.
  - isCacheEnabled
```
boolean isCacheEnabled()
```
  - getMaxSize
```
public long getMaxSize()
```
  - getIoEngine
```
public String getIoEngine()
```
  - getIOEngineFromName
```
private IOEngine getIOEngineFromName(String ioEngineName,
                           long capacity)
                              throws IOException
```
    Get the IOEngine from the IO engine name
    
    Parameters:
    ioEngineName -
    capacity -
    
    Returns:
    the IOEngine
    
    Throws:
    
    IOException
  - 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,
              boolean cacheDataInL1)
```
    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
    cacheDataInL1 -
  - 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
  - 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,
                BucketCache.BucketEntry bucketEntry,
                boolean decrementBlockNumber)
```
  - 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
  - logStats
```
public void logStats()
```
  - getRealCacheSize
```
public long getRealCacheSize()
```
  - acceptableSize
```
private long acceptableSize()
```
  - singleSize
```
private long singleSize()
```
  - multiSize
```
private long multiSize()
```
  - memorySize
```
private long memorySize()
```
  - bucketSizesAboveThresholdCount
```
private int bucketSizesAboveThresholdCount(float minFactor)
```
    Return the count of bucketSizeinfos still needf ree 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
  - freeSpace
```
private 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
  - getRAMQueueEntries
```
static List<BucketCache.RAMQueueEntry> getRAMQueueEntries(BlockingQueue<BucketCache.RAMQueueEntry> q,
                                                 List<BucketCache.RAMQueueEntry> receptical)
                                                   throws InterruptedException
```
    Blocks until elements available in q then tries to grab as many as possible before returning.
    
    Parameters:
    recepticle - Where to stash the elements taken from queue. We clear before we use it just in case.
    q - The queue to take from.
    
    Returns:
    receptical laden with elements taken from the queue or empty if none found.
    Throws: InterruptedException
  persistToFile private void persistToFile() throws IOException Throws: IOException retrieveFromFile private void retrieveFromFile(int[] bucketSizes) throws IOException, BucketAllocatorException, ClassNotFoundException Throws: IOException BucketAllocatorException ClassNotFoundException 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 getStats public CacheStats getStats() Description copied from interface: BlockCache Get the statistics for this block cache. Specified by: getStats in interface BlockCache Returns: Stats getAllocator public BucketAllocator getAllocator() heapSize public long heapSize() Specified by: heapSize in interface HeapSize Returns: Approximate 'exclusive deep size' of implementing object. Includes count of payload and hosting object sizings. 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 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 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 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 stopWriterThreads void stopWriterThreads() throws InterruptedException Only used in test Throws: InterruptedException iterator public Iterator<CachedBlock> iterator() Specified by: iterator in interface Iterable<CachedBlock> Specified by: iterator in interface BlockCache Returns: Iterator over the blocks in the cache. getBlockCaches public BlockCache[] getBlockCaches() Specified by: getBlockCaches in interface BlockCache Returns: The list of sub blockcaches that make up this one; returns null if no sub caches.

Class BucketCache

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LOG

DEFAULT_SINGLE_FACTOR

DEFAULT_MULTI_FACTOR

DEFAULT_MEMORY_FACTOR

DEFAULT_EXTRA_FREE_FACTOR

DEFAULT_ACCEPT_FACTOR

DEFAULT_MIN_FACTOR

DEFAULT_FREE_ENTIRE_BLOCK_FACTOR

statThreadPeriod

DEFAULT_WRITER_THREADS

DEFAULT_WRITER_QUEUE_ITEMS

ioEngine

ramCache

backingMap

cacheEnabled

writerQueues

writerThreads

freeInProgress

freeSpaceLock

deserialiserMap

realCacheSize

heapSize

blockNumber

accessCount

DEFAULT_CACHE_WAIT_TIME

wait_when_cache

cacheStats

persistencePath

cacheCapacity

blockSize

ioErrorsTolerationDuration

DEFAULT_ERROR_TOLERATION_DURATION

ioErrorStartTime

offsetLock

blocksByHFile

scheduleThreadPool

bucketAllocator

Constructor Detail

BucketCache

BucketCache

Method Detail

startWriterThreads

isCacheEnabled

getMaxSize

getIoEngine

getIOEngineFromName

cacheBlock

cacheBlock

cacheBlockWithWait

getBlock

blockEvicted

evictBlock

logStats

getRealCacheSize

acceptableSize

singleSize

multiSize

memorySize

bucketSizesAboveThresholdCount

freeEntireBuckets

freeSpace

getRAMQueueEntries

persistToFile

retrieveFromFile

checkIOErrorIsTolerated

disableCache

join

shutdown

getStats

getAllocator

heapSize

size

getFreeSize