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}