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.Optional; 021import org.apache.hadoop.conf.Configuration; 022import org.apache.hadoop.hbase.client.ColumnFamilyDescriptor; 023import org.apache.hadoop.hbase.conf.ConfigurationObserver; 024import org.apache.hadoop.hbase.io.ByteBuffAllocator; 025import org.apache.hadoop.hbase.io.hfile.BlockType.BlockCategory; 026import org.apache.yetus.audience.InterfaceAudience; 027import org.slf4j.Logger; 028import org.slf4j.LoggerFactory; 029 030/** 031 * Stores all of the cache objects and configuration for a single HFile. 032 */ 033@InterfaceAudience.Private 034public class CacheConfig implements ConfigurationObserver { 035 private static final Logger LOG = LoggerFactory.getLogger(CacheConfig.class.getName()); 036 037 /** 038 * Disabled cache configuration 039 */ 040 public static final CacheConfig DISABLED = new CacheConfig(); 041 042 /** 043 * Configuration key to cache data blocks on read. Bloom blocks and index blocks are always be 044 * cached if the block cache is enabled. 045 */ 046 public static final String CACHE_DATA_ON_READ_KEY = "hbase.block.data.cacheonread"; 047 048 /** 049 * Configuration key to cache data blocks on write. There are separate switches for bloom blocks 050 * and non-root index blocks. 051 */ 052 public static final String CACHE_BLOCKS_ON_WRITE_KEY = "hbase.rs.cacheblocksonwrite"; 053 054 /** 055 * Configuration key to cache leaf and intermediate-level index blocks on write. 056 */ 057 public static final String CACHE_INDEX_BLOCKS_ON_WRITE_KEY = "hfile.block.index.cacheonwrite"; 058 059 /** 060 * Configuration key to cache compound bloom filter blocks on write. 061 */ 062 public static final String CACHE_BLOOM_BLOCKS_ON_WRITE_KEY = "hfile.block.bloom.cacheonwrite"; 063 064 /** 065 * Configuration key to cache data blocks in compressed and/or encrypted format. 066 */ 067 public static final String CACHE_DATA_BLOCKS_COMPRESSED_KEY = "hbase.block.data.cachecompressed"; 068 069 /** 070 * Configuration key to evict all blocks of a given file from the block cache when the file is 071 * closed. 072 */ 073 public static final String EVICT_BLOCKS_ON_CLOSE_KEY = "hbase.rs.evictblocksonclose"; 074 075 /** 076 * Configuration key to prefetch all blocks of a given file into the block cache when the file is 077 * opened. 078 */ 079 public static final String PREFETCH_BLOCKS_ON_OPEN_KEY = "hbase.rs.prefetchblocksonopen"; 080 081 /** 082 * Configuration key to cache blocks when a compacted file is written 083 */ 084 public static final String CACHE_COMPACTED_BLOCKS_ON_WRITE_KEY = 085 "hbase.rs.cachecompactedblocksonwrite"; 086 087 /** 088 * Configuration key to determine total size in bytes of compacted files beyond which we do not 089 * cache blocks on compaction 090 */ 091 public static final String CACHE_COMPACTED_BLOCKS_ON_WRITE_THRESHOLD_KEY = 092 "hbase.rs.cachecompactedblocksonwrite.threshold"; 093 094 public static final String DROP_BEHIND_CACHE_COMPACTION_KEY = 095 "hbase.hfile.drop.behind.compaction"; 096 097 /** 098 * Configuration key to set interval for persisting bucket cache to disk. 099 */ 100 public static final String BUCKETCACHE_PERSIST_INTERVAL_KEY = 101 "hbase.bucketcache.persist.intervalinmillis"; 102 103 /** 104 * Configuration key to set the heap usage threshold limit once prefetch threads should be 105 * interrupted. 106 */ 107 public static final String PREFETCH_HEAP_USAGE_THRESHOLD = "hbase.rs.prefetchheapusage"; 108 109 // Defaults 110 public static final boolean DEFAULT_CACHE_DATA_ON_READ = true; 111 public static final boolean DEFAULT_CACHE_DATA_ON_WRITE = false; 112 public static final boolean DEFAULT_IN_MEMORY = false; 113 public static final boolean DEFAULT_CACHE_INDEXES_ON_WRITE = false; 114 public static final boolean DEFAULT_CACHE_BLOOMS_ON_WRITE = false; 115 public static final boolean DEFAULT_EVICT_ON_CLOSE = false; 116 public static final boolean DEFAULT_CACHE_DATA_COMPRESSED = false; 117 public static final boolean DEFAULT_PREFETCH_ON_OPEN = false; 118 public static final boolean DEFAULT_CACHE_COMPACTED_BLOCKS_ON_WRITE = false; 119 public static final boolean DROP_BEHIND_CACHE_COMPACTION_DEFAULT = true; 120 public static final long DEFAULT_CACHE_COMPACTED_BLOCKS_ON_WRITE_THRESHOLD = Long.MAX_VALUE; 121 public static final double DEFAULT_PREFETCH_HEAP_USAGE_THRESHOLD = 1d; 122 123 /** 124 * Whether blocks should be cached on read (default is on if there is a cache but this can be 125 * turned off on a per-family or per-request basis). If off we will STILL cache meta blocks; i.e. 126 * INDEX and BLOOM types. This cannot be disabled. 127 */ 128 private volatile boolean cacheDataOnRead; 129 130 /** Whether blocks should be flagged as in-memory when being cached */ 131 private final boolean inMemory; 132 133 /** Whether data blocks should be cached when new files are written */ 134 private volatile boolean cacheDataOnWrite; 135 136 /** Whether index blocks should be cached when new files are written */ 137 private boolean cacheIndexesOnWrite; 138 139 /** Whether compound bloom filter blocks should be cached on write */ 140 private boolean cacheBloomsOnWrite; 141 142 /** Whether blocks of a file should be evicted when the file is closed */ 143 private volatile boolean evictOnClose; 144 145 /** Whether data blocks should be stored in compressed and/or encrypted form in the cache */ 146 private final boolean cacheDataCompressed; 147 148 /** Whether data blocks should be prefetched into the cache */ 149 private final boolean prefetchOnOpen; 150 151 /** 152 * Whether data blocks should be cached when compacted file is written 153 */ 154 private final boolean cacheCompactedDataOnWrite; 155 156 /** 157 * Determine threshold beyond which we do not cache blocks on compaction 158 */ 159 private long cacheCompactedDataOnWriteThreshold; 160 161 private final boolean dropBehindCompaction; 162 163 // Local reference to the block cache 164 private final BlockCache blockCache; 165 166 private final ByteBuffAllocator byteBuffAllocator; 167 168 private final double heapUsageThreshold; 169 170 /** 171 * Create a cache configuration using the specified configuration object and defaults for family 172 * level settings. Only use if no column family context. 173 * @param conf hbase configuration 174 */ 175 public CacheConfig(Configuration conf) { 176 this(conf, null); 177 } 178 179 public CacheConfig(Configuration conf, BlockCache blockCache) { 180 this(conf, null, blockCache, ByteBuffAllocator.HEAP); 181 } 182 183 /** 184 * Create a cache configuration using the specified configuration object and family descriptor. 185 * @param conf hbase configuration 186 * @param family column family configuration 187 */ 188 public CacheConfig(Configuration conf, ColumnFamilyDescriptor family, BlockCache blockCache, 189 ByteBuffAllocator byteBuffAllocator) { 190 this.cacheDataOnRead = conf.getBoolean(CACHE_DATA_ON_READ_KEY, DEFAULT_CACHE_DATA_ON_READ) 191 && (family == null ? true : family.isBlockCacheEnabled()); 192 this.inMemory = family == null ? DEFAULT_IN_MEMORY : family.isInMemory(); 193 this.cacheDataCompressed = 194 conf.getBoolean(CACHE_DATA_BLOCKS_COMPRESSED_KEY, DEFAULT_CACHE_DATA_COMPRESSED); 195 this.dropBehindCompaction = 196 conf.getBoolean(DROP_BEHIND_CACHE_COMPACTION_KEY, DROP_BEHIND_CACHE_COMPACTION_DEFAULT); 197 // For the following flags we enable them regardless of per-schema settings 198 // if they are enabled in the global configuration. 199 this.cacheDataOnWrite = conf.getBoolean(CACHE_BLOCKS_ON_WRITE_KEY, DEFAULT_CACHE_DATA_ON_WRITE) 200 || (family == null ? false : family.isCacheDataOnWrite()); 201 this.cacheIndexesOnWrite = 202 conf.getBoolean(CACHE_INDEX_BLOCKS_ON_WRITE_KEY, DEFAULT_CACHE_INDEXES_ON_WRITE) 203 || (family == null ? false : family.isCacheIndexesOnWrite()); 204 this.cacheBloomsOnWrite = 205 conf.getBoolean(CACHE_BLOOM_BLOCKS_ON_WRITE_KEY, DEFAULT_CACHE_BLOOMS_ON_WRITE) 206 || (family == null ? false : family.isCacheBloomsOnWrite()); 207 this.evictOnClose = conf.getBoolean(EVICT_BLOCKS_ON_CLOSE_KEY, DEFAULT_EVICT_ON_CLOSE) 208 || (family == null ? false : family.isEvictBlocksOnClose()); 209 this.prefetchOnOpen = conf.getBoolean(PREFETCH_BLOCKS_ON_OPEN_KEY, DEFAULT_PREFETCH_ON_OPEN) 210 || (family == null ? false : family.isPrefetchBlocksOnOpen()); 211 this.cacheCompactedDataOnWrite = 212 conf.getBoolean(CACHE_COMPACTED_BLOCKS_ON_WRITE_KEY, DEFAULT_CACHE_COMPACTED_BLOCKS_ON_WRITE); 213 this.cacheCompactedDataOnWriteThreshold = getCacheCompactedBlocksOnWriteThreshold(conf); 214 this.heapUsageThreshold = 215 conf.getDouble(PREFETCH_HEAP_USAGE_THRESHOLD, DEFAULT_PREFETCH_HEAP_USAGE_THRESHOLD); 216 this.blockCache = blockCache; 217 this.byteBuffAllocator = byteBuffAllocator; 218 } 219 220 /** 221 * Constructs a cache configuration copied from the specified configuration. 222 */ 223 public CacheConfig(CacheConfig cacheConf) { 224 this.cacheDataOnRead = cacheConf.cacheDataOnRead; 225 this.inMemory = cacheConf.inMemory; 226 this.cacheDataOnWrite = cacheConf.cacheDataOnWrite; 227 this.cacheIndexesOnWrite = cacheConf.cacheIndexesOnWrite; 228 this.cacheBloomsOnWrite = cacheConf.cacheBloomsOnWrite; 229 this.evictOnClose = cacheConf.evictOnClose; 230 this.cacheDataCompressed = cacheConf.cacheDataCompressed; 231 this.prefetchOnOpen = cacheConf.prefetchOnOpen; 232 this.cacheCompactedDataOnWrite = cacheConf.cacheCompactedDataOnWrite; 233 this.cacheCompactedDataOnWriteThreshold = cacheConf.cacheCompactedDataOnWriteThreshold; 234 this.dropBehindCompaction = cacheConf.dropBehindCompaction; 235 this.blockCache = cacheConf.blockCache; 236 this.byteBuffAllocator = cacheConf.byteBuffAllocator; 237 this.heapUsageThreshold = cacheConf.heapUsageThreshold; 238 } 239 240 private CacheConfig() { 241 this.cacheDataOnRead = false; 242 this.inMemory = false; 243 this.cacheDataOnWrite = false; 244 this.cacheIndexesOnWrite = false; 245 this.cacheBloomsOnWrite = false; 246 this.evictOnClose = false; 247 this.cacheDataCompressed = false; 248 this.prefetchOnOpen = false; 249 this.cacheCompactedDataOnWrite = false; 250 this.dropBehindCompaction = false; 251 this.blockCache = null; 252 this.byteBuffAllocator = ByteBuffAllocator.HEAP; 253 this.heapUsageThreshold = DEFAULT_PREFETCH_HEAP_USAGE_THRESHOLD; 254 } 255 256 /** 257 * Returns whether the DATA blocks of this HFile should be cached on read or not (we always cache 258 * the meta blocks, the INDEX and BLOOM blocks). 259 * @return true if blocks should be cached on read, false if not 260 */ 261 public boolean shouldCacheDataOnRead() { 262 return cacheDataOnRead; 263 } 264 265 public boolean shouldDropBehindCompaction() { 266 return dropBehindCompaction; 267 } 268 269 /** 270 * Should we cache a block of a particular category? We always cache important blocks such as 271 * index blocks, as long as the block cache is available. 272 */ 273 public boolean shouldCacheBlockOnRead(BlockCategory category) { 274 return cacheDataOnRead || category == BlockCategory.INDEX || category == BlockCategory.BLOOM 275 || (prefetchOnOpen && (category != BlockCategory.META && category != BlockCategory.UNKNOWN)); 276 } 277 278 /** Returns true if blocks in this file should be flagged as in-memory */ 279 public boolean isInMemory() { 280 return this.inMemory; 281 } 282 283 /** 284 * @return true if data blocks should be written to the cache when an HFile is written, false if 285 * not 286 */ 287 public boolean shouldCacheDataOnWrite() { 288 return this.cacheDataOnWrite; 289 } 290 291 /** 292 * @param cacheDataOnWrite whether data blocks should be written to the cache when an HFile is 293 * written 294 */ 295 public void setCacheDataOnWrite(boolean cacheDataOnWrite) { 296 this.cacheDataOnWrite = cacheDataOnWrite; 297 } 298 299 /** 300 * Enable cache on write including: cacheDataOnWrite cacheIndexesOnWrite cacheBloomsOnWrite 301 */ 302 public void enableCacheOnWrite() { 303 this.cacheDataOnWrite = true; 304 this.cacheIndexesOnWrite = true; 305 this.cacheBloomsOnWrite = true; 306 } 307 308 /** 309 * @return true if index blocks should be written to the cache when an HFile is written, false if 310 * not 311 */ 312 public boolean shouldCacheIndexesOnWrite() { 313 return this.cacheIndexesOnWrite; 314 } 315 316 /** 317 * @return true if bloom blocks should be written to the cache when an HFile is written, false if 318 * not 319 */ 320 public boolean shouldCacheBloomsOnWrite() { 321 return this.cacheBloomsOnWrite; 322 } 323 324 /** 325 * @return true if blocks should be evicted from the cache when an HFile reader is closed, false 326 * if not 327 */ 328 public boolean shouldEvictOnClose() { 329 return this.evictOnClose; 330 } 331 332 /** 333 * Only used for testing. 334 * @param evictOnClose whether blocks should be evicted from the cache when an HFile reader is 335 * closed 336 */ 337 public void setEvictOnClose(boolean evictOnClose) { 338 this.evictOnClose = evictOnClose; 339 } 340 341 /** Returns true if data blocks should be compressed in the cache, false if not */ 342 public boolean shouldCacheDataCompressed() { 343 return this.cacheDataOnRead && this.cacheDataCompressed; 344 } 345 346 /** 347 * Returns true if this {@link BlockCategory} should be compressed in blockcache, false otherwise 348 */ 349 public boolean shouldCacheCompressed(BlockCategory category) { 350 switch (category) { 351 case DATA: 352 return this.cacheDataOnRead && this.cacheDataCompressed; 353 default: 354 return false; 355 } 356 } 357 358 /** Returns true if blocks should be prefetched into the cache on open, false if not */ 359 public boolean shouldPrefetchOnOpen() { 360 return this.prefetchOnOpen && this.cacheDataOnRead; 361 } 362 363 /** Returns true if blocks should be cached while writing during compaction, false if not */ 364 public boolean shouldCacheCompactedBlocksOnWrite() { 365 return this.cacheCompactedDataOnWrite; 366 } 367 368 /** Returns total file size in bytes threshold for caching while writing during compaction */ 369 public long getCacheCompactedBlocksOnWriteThreshold() { 370 return this.cacheCompactedDataOnWriteThreshold; 371 } 372 373 /** 374 * Return true if we may find this type of block in block cache. 375 * <p> 376 * TODO: today {@code family.isBlockCacheEnabled()} only means {@code cacheDataOnRead}, so here we 377 * consider lots of other configurations such as {@code cacheDataOnWrite}. We should fix this in 378 * the future, {@code cacheDataOnWrite} should honor the CF level {@code isBlockCacheEnabled} 379 * configuration. 380 */ 381 public boolean shouldReadBlockFromCache(BlockType blockType) { 382 if (cacheDataOnRead) { 383 return true; 384 } 385 if (prefetchOnOpen) { 386 return true; 387 } 388 if (cacheDataOnWrite) { 389 return true; 390 } 391 if (blockType == null) { 392 return true; 393 } 394 if ( 395 blockType.getCategory() == BlockCategory.BLOOM 396 || blockType.getCategory() == BlockCategory.INDEX 397 ) { 398 return true; 399 } 400 return false; 401 } 402 403 /** 404 * Checks if the current heap usage is below the threshold configured by 405 * "hbase.rs.prefetchheapusage" (0.8 by default). 406 */ 407 public boolean isHeapUsageBelowThreshold() { 408 double total = Runtime.getRuntime().maxMemory(); 409 double available = Runtime.getRuntime().freeMemory(); 410 double usedRatio = 1d - (available / total); 411 return heapUsageThreshold > usedRatio; 412 } 413 414 /** 415 * If we make sure the block could not be cached, we will not acquire the lock otherwise we will 416 * acquire lock 417 */ 418 public boolean shouldLockOnCacheMiss(BlockType blockType) { 419 if (blockType == null) { 420 return true; 421 } 422 return shouldCacheBlockOnRead(blockType.getCategory()); 423 } 424 425 /** 426 * Returns the block cache. 427 * @return the block cache, or null if caching is completely disabled 428 */ 429 public Optional<BlockCache> getBlockCache() { 430 return Optional.ofNullable(this.blockCache); 431 } 432 433 public boolean isCombinedBlockCache() { 434 return blockCache instanceof CombinedBlockCache; 435 } 436 437 public ByteBuffAllocator getByteBuffAllocator() { 438 return this.byteBuffAllocator; 439 } 440 441 public double getHeapUsageThreshold() { 442 return heapUsageThreshold; 443 } 444 445 private long getCacheCompactedBlocksOnWriteThreshold(Configuration conf) { 446 long cacheCompactedBlocksOnWriteThreshold = 447 conf.getLong(CACHE_COMPACTED_BLOCKS_ON_WRITE_THRESHOLD_KEY, 448 DEFAULT_CACHE_COMPACTED_BLOCKS_ON_WRITE_THRESHOLD); 449 450 if (cacheCompactedBlocksOnWriteThreshold < 0) { 451 LOG.warn( 452 "cacheCompactedBlocksOnWriteThreshold value : {} is less than 0, resetting it to: {}", 453 cacheCompactedBlocksOnWriteThreshold, DEFAULT_CACHE_COMPACTED_BLOCKS_ON_WRITE_THRESHOLD); 454 cacheCompactedBlocksOnWriteThreshold = DEFAULT_CACHE_COMPACTED_BLOCKS_ON_WRITE_THRESHOLD; 455 } 456 457 return cacheCompactedBlocksOnWriteThreshold; 458 } 459 460 @Override 461 public String toString() { 462 return "cacheDataOnRead=" + shouldCacheDataOnRead() + ", cacheDataOnWrite=" 463 + shouldCacheDataOnWrite() + ", cacheIndexesOnWrite=" + shouldCacheIndexesOnWrite() 464 + ", cacheBloomsOnWrite=" + shouldCacheBloomsOnWrite() + ", cacheEvictOnClose=" 465 + shouldEvictOnClose() + ", cacheDataCompressed=" + shouldCacheDataCompressed() 466 + ", prefetchOnOpen=" + shouldPrefetchOnOpen(); 467 } 468 469 @Override 470 public void onConfigurationChange(Configuration conf) { 471 cacheDataOnRead = conf.getBoolean(CACHE_DATA_ON_READ_KEY, DEFAULT_CACHE_DATA_ON_READ); 472 cacheDataOnWrite = conf.getBoolean(CACHE_BLOCKS_ON_WRITE_KEY, DEFAULT_CACHE_DATA_ON_WRITE); 473 evictOnClose = conf.getBoolean(EVICT_BLOCKS_ON_CLOSE_KEY, DEFAULT_EVICT_ON_CLOSE); 474 LOG.info( 475 "Config hbase.block.data.cacheonread is changed to {}, " 476 + "hbase.rs.cacheblocksonwrite is changed to {}, " 477 + "hbase.rs.evictblocksonclose is changed to {}", 478 cacheDataOnRead, cacheDataOnWrite, evictOnClose); 479 } 480}