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