001/**
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *     http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019package org.apache.hadoop.hbase.io.hfile;
020
021import java.util.Iterator;
022
023import org.apache.yetus.audience.InterfaceAudience;
024
025/**
026 * Block cache interface. Anything that implements the {@link Cacheable}
027 * interface can be put in the cache.
028 */
029@InterfaceAudience.Private
030public interface BlockCache extends Iterable<CachedBlock> {
031  /**
032   * Add block to cache.
033   * @param cacheKey The block's cache key.
034   * @param buf The block contents wrapped in a ByteBuffer.
035   * @param inMemory Whether block should be treated as in-memory
036   */
037  void cacheBlock(BlockCacheKey cacheKey, Cacheable buf, boolean inMemory);
038
039  /**
040   * Add block to cache (defaults to not in-memory).
041   * @param cacheKey The block's cache key.
042   * @param buf The object to cache.
043   */
044  void cacheBlock(BlockCacheKey cacheKey, Cacheable buf);
045
046  /**
047   * Fetch block from cache.
048   * @param cacheKey Block to fetch.
049   * @param caching Whether this request has caching enabled (used for stats)
050   * @param repeat Whether this is a repeat lookup for the same block
051   *        (used to avoid double counting cache misses when doing double-check locking)
052   * @param updateCacheMetrics Whether to update cache metrics or not
053   * @return Block or null if block is not in 2 cache.
054   */
055  Cacheable getBlock(BlockCacheKey cacheKey, boolean caching, boolean repeat,
056    boolean updateCacheMetrics);
057
058  /**
059   * Evict block from cache.
060   * @param cacheKey Block to evict
061   * @return true if block existed and was evicted, false if not
062   */
063  boolean evictBlock(BlockCacheKey cacheKey);
064
065  /**
066   * Evicts all blocks for the given HFile.
067   *
068   * @return the number of blocks evicted
069   */
070  int evictBlocksByHfileName(String hfileName);
071
072  /**
073   * Get the statistics for this block cache.
074   * @return Stats
075   */
076  CacheStats getStats();
077
078  /**
079   * Shutdown the cache.
080   */
081  void shutdown();
082
083  /**
084   * Returns the total size of the block cache, in bytes.
085   * @return size of cache, in bytes
086   */
087  long size();
088
089  /**
090   * Returns the Max size of the block cache, in bytes.
091   * @return size of cache, in bytes
092   */
093  long getMaxSize();
094
095  /**
096   * Returns the free size of the block cache, in bytes.
097   * @return free space in cache, in bytes
098   */
099  long getFreeSize();
100
101  /**
102   * Returns the occupied size of the block cache, in bytes.
103   * @return occupied space in cache, in bytes
104   */
105  long getCurrentSize();
106
107  /**
108   * Returns the occupied size of data blocks, in bytes.
109   * @return occupied space in cache, in bytes
110   */
111  long getCurrentDataSize();
112
113  /**
114   * Returns the number of blocks currently cached in the block cache.
115   * @return number of blocks in the cache
116   */
117  long getBlockCount();
118
119 /**
120  * Returns the number of data blocks currently cached in the block cache.
121  * @return number of blocks in the cache
122  */
123 long getDataBlockCount();
124
125  /**
126   * @return Iterator over the blocks in the cache.
127   */
128  @Override
129  Iterator<CachedBlock> iterator();
130
131  /**
132   * @return The list of sub blockcaches that make up this one; returns null if no sub caches.
133   */
134  BlockCache [] getBlockCaches();
135}