]>
Commit | Line | Data |
---|---|---|
7c673cae | 1 | // Copyright (c) 2011-present, Facebook, Inc. All rights reserved. |
11fdf7f2 TL |
2 | // This source code is licensed under both the GPLv2 (found in the |
3 | // COPYING file in the root directory) and Apache 2.0 License | |
4 | // (found in the LICENSE.Apache file in the root directory). | |
7c673cae FG |
5 | package org.rocksdb; |
6 | ||
7 | /** | |
8 | * The config for plain table sst format. | |
9 | * | |
10 | * BlockBasedTable is a RocksDB's default SST file format. | |
11 | */ | |
12 | public class BlockBasedTableConfig extends TableFormatConfig { | |
13 | ||
14 | public BlockBasedTableConfig() { | |
15 | noBlockCache_ = false; | |
16 | blockCacheSize_ = 8 * 1024 * 1024; | |
17 | blockCacheNumShardBits_ = 0; | |
11fdf7f2 | 18 | blockCache_ = null; |
7c673cae FG |
19 | blockSize_ = 4 * 1024; |
20 | blockSizeDeviation_ = 10; | |
21 | blockRestartInterval_ = 16; | |
22 | wholeKeyFiltering_ = true; | |
23 | filter_ = null; | |
24 | cacheIndexAndFilterBlocks_ = false; | |
25 | pinL0FilterAndIndexBlocksInCache_ = false; | |
26 | hashIndexAllowCollision_ = true; | |
27 | blockCacheCompressedSize_ = 0; | |
28 | blockCacheCompressedNumShardBits_ = 0; | |
29 | checksumType_ = ChecksumType.kCRC32c; | |
30 | indexType_ = IndexType.kBinarySearch; | |
31 | formatVersion_ = 0; | |
32 | } | |
33 | ||
34 | /** | |
35 | * Disable block cache. If this is set to true, | |
36 | * then no block cache should be used, and the block_cache should | |
37 | * point to a {@code nullptr} object. | |
38 | * Default: false | |
39 | * | |
40 | * @param noBlockCache if use block cache | |
41 | * @return the reference to the current config. | |
42 | */ | |
43 | public BlockBasedTableConfig setNoBlockCache(final boolean noBlockCache) { | |
44 | noBlockCache_ = noBlockCache; | |
45 | return this; | |
46 | } | |
47 | ||
48 | /** | |
49 | * @return if block cache is disabled | |
50 | */ | |
51 | public boolean noBlockCache() { | |
52 | return noBlockCache_; | |
53 | } | |
54 | ||
55 | /** | |
56 | * Set the amount of cache in bytes that will be used by RocksDB. | |
57 | * If cacheSize is non-positive, then cache will not be used. | |
58 | * DEFAULT: 8M | |
59 | * | |
60 | * @param blockCacheSize block cache size in bytes | |
61 | * @return the reference to the current config. | |
62 | */ | |
63 | public BlockBasedTableConfig setBlockCacheSize(final long blockCacheSize) { | |
64 | blockCacheSize_ = blockCacheSize; | |
65 | return this; | |
66 | } | |
67 | ||
68 | /** | |
69 | * @return block cache size in bytes | |
70 | */ | |
71 | public long blockCacheSize() { | |
72 | return blockCacheSize_; | |
73 | } | |
74 | ||
11fdf7f2 TL |
75 | /** |
76 | * Use the specified cache for blocks. | |
77 | * When not null this take precedence even if the user sets a block cache size. | |
78 | * | |
79 | * {@link org.rocksdb.Cache} should not be disposed before options instances | |
80 | * using this cache is disposed. | |
81 | * | |
82 | * {@link org.rocksdb.Cache} instance can be re-used in multiple options | |
83 | * instances. | |
84 | * | |
85 | * @param cache {@link org.rocksdb.Cache} Cache java instance (e.g. LRUCache). | |
86 | * @return the reference to the current config. | |
87 | */ | |
88 | public BlockBasedTableConfig setBlockCache(final Cache cache) { | |
89 | blockCache_ = cache; | |
90 | return this; | |
91 | } | |
92 | ||
7c673cae FG |
93 | /** |
94 | * Controls the number of shards for the block cache. | |
95 | * This is applied only if cacheSize is set to non-negative. | |
96 | * | |
97 | * @param blockCacheNumShardBits the number of shard bits. The resulting | |
98 | * number of shards would be 2 ^ numShardBits. Any negative | |
99 | * number means use default settings." | |
100 | * @return the reference to the current option. | |
101 | */ | |
102 | public BlockBasedTableConfig setCacheNumShardBits( | |
103 | final int blockCacheNumShardBits) { | |
104 | blockCacheNumShardBits_ = blockCacheNumShardBits; | |
105 | return this; | |
106 | } | |
107 | ||
108 | /** | |
109 | * Returns the number of shard bits used in the block cache. | |
110 | * The resulting number of shards would be 2 ^ (returned value). | |
111 | * Any negative number means use default settings. | |
112 | * | |
113 | * @return the number of shard bits used in the block cache. | |
114 | */ | |
115 | public int cacheNumShardBits() { | |
116 | return blockCacheNumShardBits_; | |
117 | } | |
118 | ||
119 | /** | |
120 | * Approximate size of user data packed per block. Note that the | |
121 | * block size specified here corresponds to uncompressed data. The | |
122 | * actual size of the unit read from disk may be smaller if | |
123 | * compression is enabled. This parameter can be changed dynamically. | |
124 | * Default: 4K | |
125 | * | |
126 | * @param blockSize block size in bytes | |
127 | * @return the reference to the current config. | |
128 | */ | |
129 | public BlockBasedTableConfig setBlockSize(final long blockSize) { | |
130 | blockSize_ = blockSize; | |
131 | return this; | |
132 | } | |
133 | ||
134 | /** | |
135 | * @return block size in bytes | |
136 | */ | |
137 | public long blockSize() { | |
138 | return blockSize_; | |
139 | } | |
140 | ||
141 | /** | |
142 | * This is used to close a block before it reaches the configured | |
143 | * 'block_size'. If the percentage of free space in the current block is less | |
144 | * than this specified number and adding a new record to the block will | |
145 | * exceed the configured block size, then this block will be closed and the | |
146 | * new record will be written to the next block. | |
147 | * Default is 10. | |
148 | * | |
149 | * @param blockSizeDeviation the deviation to block size allowed | |
150 | * @return the reference to the current config. | |
151 | */ | |
152 | public BlockBasedTableConfig setBlockSizeDeviation( | |
153 | final int blockSizeDeviation) { | |
154 | blockSizeDeviation_ = blockSizeDeviation; | |
155 | return this; | |
156 | } | |
157 | ||
158 | /** | |
159 | * @return the hash table ratio. | |
160 | */ | |
161 | public int blockSizeDeviation() { | |
162 | return blockSizeDeviation_; | |
163 | } | |
164 | ||
165 | /** | |
166 | * Set block restart interval | |
167 | * | |
168 | * @param restartInterval block restart interval. | |
169 | * @return the reference to the current config. | |
170 | */ | |
171 | public BlockBasedTableConfig setBlockRestartInterval( | |
172 | final int restartInterval) { | |
173 | blockRestartInterval_ = restartInterval; | |
174 | return this; | |
175 | } | |
176 | ||
177 | /** | |
178 | * @return block restart interval | |
179 | */ | |
180 | public int blockRestartInterval() { | |
181 | return blockRestartInterval_; | |
182 | } | |
183 | ||
184 | /** | |
185 | * If true, place whole keys in the filter (not just prefixes). | |
186 | * This must generally be true for gets to be efficient. | |
187 | * Default: true | |
188 | * | |
189 | * @param wholeKeyFiltering if enable whole key filtering | |
190 | * @return the reference to the current config. | |
191 | */ | |
192 | public BlockBasedTableConfig setWholeKeyFiltering( | |
193 | final boolean wholeKeyFiltering) { | |
194 | wholeKeyFiltering_ = wholeKeyFiltering; | |
195 | return this; | |
196 | } | |
197 | ||
198 | /** | |
199 | * @return if whole key filtering is enabled | |
200 | */ | |
201 | public boolean wholeKeyFiltering() { | |
202 | return wholeKeyFiltering_; | |
203 | } | |
204 | ||
205 | /** | |
206 | * Use the specified filter policy to reduce disk reads. | |
207 | * | |
208 | * {@link org.rocksdb.Filter} should not be disposed before options instances | |
209 | * using this filter is disposed. If {@link Filter#dispose()} function is not | |
210 | * called, then filter object will be GC'd automatically. | |
211 | * | |
212 | * {@link org.rocksdb.Filter} instance can be re-used in multiple options | |
213 | * instances. | |
214 | * | |
215 | * @param filter {@link org.rocksdb.Filter} Filter Policy java instance. | |
216 | * @return the reference to the current config. | |
217 | */ | |
218 | public BlockBasedTableConfig setFilter( | |
219 | final Filter filter) { | |
220 | filter_ = filter; | |
221 | return this; | |
222 | } | |
223 | ||
224 | /** | |
225 | * Indicating if we'd put index/filter blocks to the block cache. | |
226 | If not specified, each "table reader" object will pre-load index/filter | |
227 | block during table initialization. | |
228 | * | |
229 | * @return if index and filter blocks should be put in block cache. | |
230 | */ | |
231 | public boolean cacheIndexAndFilterBlocks() { | |
232 | return cacheIndexAndFilterBlocks_; | |
233 | } | |
234 | ||
235 | /** | |
236 | * Indicating if we'd put index/filter blocks to the block cache. | |
237 | If not specified, each "table reader" object will pre-load index/filter | |
238 | block during table initialization. | |
239 | * | |
240 | * @param cacheIndexAndFilterBlocks and filter blocks should be put in block cache. | |
241 | * @return the reference to the current config. | |
242 | */ | |
243 | public BlockBasedTableConfig setCacheIndexAndFilterBlocks( | |
244 | final boolean cacheIndexAndFilterBlocks) { | |
245 | cacheIndexAndFilterBlocks_ = cacheIndexAndFilterBlocks; | |
246 | return this; | |
247 | } | |
248 | ||
249 | /** | |
250 | * Indicating if we'd like to pin L0 index/filter blocks to the block cache. | |
251 | If not specified, defaults to false. | |
252 | * | |
253 | * @return if L0 index and filter blocks should be pinned to the block cache. | |
254 | */ | |
255 | public boolean pinL0FilterAndIndexBlocksInCache() { | |
256 | return pinL0FilterAndIndexBlocksInCache_; | |
257 | } | |
258 | ||
259 | /** | |
260 | * Indicating if we'd like to pin L0 index/filter blocks to the block cache. | |
261 | If not specified, defaults to false. | |
262 | * | |
263 | * @param pinL0FilterAndIndexBlocksInCache pin blocks in block cache | |
264 | * @return the reference to the current config. | |
265 | */ | |
266 | public BlockBasedTableConfig setPinL0FilterAndIndexBlocksInCache( | |
267 | final boolean pinL0FilterAndIndexBlocksInCache) { | |
268 | pinL0FilterAndIndexBlocksInCache_ = pinL0FilterAndIndexBlocksInCache; | |
269 | return this; | |
270 | } | |
271 | ||
272 | /** | |
273 | * Influence the behavior when kHashSearch is used. | |
274 | if false, stores a precise prefix to block range mapping | |
275 | if true, does not store prefix and allows prefix hash collision | |
276 | (less memory consumption) | |
277 | * | |
278 | * @return if hash collisions should be allowed. | |
279 | */ | |
280 | public boolean hashIndexAllowCollision() { | |
281 | return hashIndexAllowCollision_; | |
282 | } | |
283 | ||
284 | /** | |
285 | * Influence the behavior when kHashSearch is used. | |
286 | if false, stores a precise prefix to block range mapping | |
287 | if true, does not store prefix and allows prefix hash collision | |
288 | (less memory consumption) | |
289 | * | |
290 | * @param hashIndexAllowCollision points out if hash collisions should be allowed. | |
291 | * @return the reference to the current config. | |
292 | */ | |
293 | public BlockBasedTableConfig setHashIndexAllowCollision( | |
294 | final boolean hashIndexAllowCollision) { | |
295 | hashIndexAllowCollision_ = hashIndexAllowCollision; | |
296 | return this; | |
297 | } | |
298 | ||
299 | /** | |
300 | * Size of compressed block cache. If 0, then block_cache_compressed is set | |
301 | * to null. | |
302 | * | |
303 | * @return size of compressed block cache. | |
304 | */ | |
305 | public long blockCacheCompressedSize() { | |
306 | return blockCacheCompressedSize_; | |
307 | } | |
308 | ||
309 | /** | |
310 | * Size of compressed block cache. If 0, then block_cache_compressed is set | |
311 | * to null. | |
312 | * | |
313 | * @param blockCacheCompressedSize of compressed block cache. | |
314 | * @return the reference to the current config. | |
315 | */ | |
316 | public BlockBasedTableConfig setBlockCacheCompressedSize( | |
317 | final long blockCacheCompressedSize) { | |
318 | blockCacheCompressedSize_ = blockCacheCompressedSize; | |
319 | return this; | |
320 | } | |
321 | ||
322 | /** | |
323 | * Controls the number of shards for the block compressed cache. | |
324 | * This is applied only if blockCompressedCacheSize is set to non-negative. | |
325 | * | |
326 | * @return numShardBits the number of shard bits. The resulting | |
327 | * number of shards would be 2 ^ numShardBits. Any negative | |
328 | * number means use default settings. | |
329 | */ | |
330 | public int blockCacheCompressedNumShardBits() { | |
331 | return blockCacheCompressedNumShardBits_; | |
332 | } | |
333 | ||
334 | /** | |
335 | * Controls the number of shards for the block compressed cache. | |
336 | * This is applied only if blockCompressedCacheSize is set to non-negative. | |
337 | * | |
338 | * @param blockCacheCompressedNumShardBits the number of shard bits. The resulting | |
339 | * number of shards would be 2 ^ numShardBits. Any negative | |
340 | * number means use default settings." | |
341 | * @return the reference to the current option. | |
342 | */ | |
343 | public BlockBasedTableConfig setBlockCacheCompressedNumShardBits( | |
344 | final int blockCacheCompressedNumShardBits) { | |
345 | blockCacheCompressedNumShardBits_ = blockCacheCompressedNumShardBits; | |
346 | return this; | |
347 | } | |
348 | ||
349 | /** | |
350 | * Sets the checksum type to be used with this table. | |
351 | * | |
352 | * @param checksumType {@link org.rocksdb.ChecksumType} value. | |
353 | * @return the reference to the current option. | |
354 | */ | |
355 | public BlockBasedTableConfig setChecksumType( | |
356 | final ChecksumType checksumType) { | |
357 | checksumType_ = checksumType; | |
358 | return this; | |
359 | } | |
360 | ||
361 | /** | |
362 | * | |
363 | * @return the currently set checksum type | |
364 | */ | |
365 | public ChecksumType checksumType() { | |
366 | return checksumType_; | |
367 | } | |
368 | ||
369 | /** | |
370 | * Sets the index type to used with this table. | |
371 | * | |
372 | * @param indexType {@link org.rocksdb.IndexType} value | |
373 | * @return the reference to the current option. | |
374 | */ | |
375 | public BlockBasedTableConfig setIndexType( | |
376 | final IndexType indexType) { | |
377 | indexType_ = indexType; | |
378 | return this; | |
379 | } | |
380 | ||
381 | /** | |
382 | * | |
383 | * @return the currently set index type | |
384 | */ | |
385 | public IndexType indexType() { | |
386 | return indexType_; | |
387 | } | |
388 | ||
389 | /** | |
390 | * <p>We currently have three versions:</p> | |
391 | * | |
392 | * <ul> | |
393 | * <li><strong>0</strong> - This version is currently written | |
394 | * out by all RocksDB's versions by default. Can be read by really old | |
395 | * RocksDB's. Doesn't support changing checksum (default is CRC32).</li> | |
396 | * <li><strong>1</strong> - Can be read by RocksDB's versions since 3.0. | |
397 | * Supports non-default checksum, like xxHash. It is written by RocksDB when | |
398 | * BlockBasedTableOptions::checksum is something other than kCRC32c. (version | |
399 | * 0 is silently upconverted)</li> | |
400 | * <li><strong>2</strong> - Can be read by RocksDB's versions since 3.10. | |
401 | * Changes the way we encode compressed blocks with LZ4, BZip2 and Zlib | |
402 | * compression. If you don't plan to run RocksDB before version 3.10, | |
403 | * you should probably use this.</li> | |
404 | * </ul> | |
405 | * <p> This option only affects newly written tables. When reading existing | |
406 | * tables, the information about version is read from the footer.</p> | |
407 | * | |
408 | * @param formatVersion integer representing the version to be used. | |
409 | * @return the reference to the current option. | |
410 | */ | |
411 | public BlockBasedTableConfig setFormatVersion( | |
412 | final int formatVersion) { | |
413 | assert(formatVersion >= 0 && formatVersion <= 2); | |
414 | formatVersion_ = formatVersion; | |
415 | return this; | |
416 | } | |
417 | ||
418 | /** | |
419 | * | |
420 | * @return the currently configured format version. | |
421 | * See also: {@link #setFormatVersion(int)}. | |
422 | */ | |
423 | public int formatVersion() { | |
424 | return formatVersion_; | |
425 | } | |
426 | ||
427 | ||
428 | ||
429 | @Override protected long newTableFactoryHandle() { | |
430 | long filterHandle = 0; | |
431 | if (filter_ != null) { | |
432 | filterHandle = filter_.nativeHandle_; | |
433 | } | |
434 | ||
11fdf7f2 TL |
435 | long blockCacheHandle = 0; |
436 | if (blockCache_ != null) { | |
437 | blockCacheHandle = blockCache_.nativeHandle_; | |
438 | } | |
439 | ||
440 | return newTableFactoryHandle(noBlockCache_, blockCacheSize_, blockCacheNumShardBits_, | |
441 | blockCacheHandle, blockSize_, blockSizeDeviation_, blockRestartInterval_, | |
442 | wholeKeyFiltering_, filterHandle, cacheIndexAndFilterBlocks_, | |
443 | pinL0FilterAndIndexBlocksInCache_, hashIndexAllowCollision_, blockCacheCompressedSize_, | |
444 | blockCacheCompressedNumShardBits_, checksumType_.getValue(), indexType_.getValue(), | |
7c673cae FG |
445 | formatVersion_); |
446 | } | |
447 | ||
11fdf7f2 TL |
448 | private native long newTableFactoryHandle(boolean noBlockCache, long blockCacheSize, |
449 | int blockCacheNumShardBits, long blockCacheHandle, long blockSize, int blockSizeDeviation, | |
450 | int blockRestartInterval, boolean wholeKeyFiltering, long filterPolicyHandle, | |
7c673cae FG |
451 | boolean cacheIndexAndFilterBlocks, boolean pinL0FilterAndIndexBlocksInCache, |
452 | boolean hashIndexAllowCollision, long blockCacheCompressedSize, | |
11fdf7f2 | 453 | int blockCacheCompressedNumShardBits, byte checkSumType, byte indexType, int formatVersion); |
7c673cae FG |
454 | |
455 | private boolean cacheIndexAndFilterBlocks_; | |
456 | private boolean pinL0FilterAndIndexBlocksInCache_; | |
457 | private IndexType indexType_; | |
458 | private boolean hashIndexAllowCollision_; | |
459 | private ChecksumType checksumType_; | |
460 | private boolean noBlockCache_; | |
461 | private long blockSize_; | |
462 | private long blockCacheSize_; | |
463 | private int blockCacheNumShardBits_; | |
11fdf7f2 | 464 | private Cache blockCache_; |
7c673cae FG |
465 | private long blockCacheCompressedSize_; |
466 | private int blockCacheCompressedNumShardBits_; | |
467 | private int blockSizeDeviation_; | |
468 | private int blockRestartInterval_; | |
469 | private Filter filter_; | |
470 | private boolean wholeKeyFiltering_; | |
471 | private int formatVersion_; | |
472 | } |