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