andreacavalli/rocksdb
0
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Correct java docs of RocksDB options (#6123)

Browse Source 
Summary:
Correct javadocs of several RocksDB option classes to not mislead RocksJava users.
Pull Request resolved: https://github.com/facebook/rocksdb/pull/6123

Differential Revision: D18989044

Pulled By: pdillinger

fbshipit-source-id: a5ac6a415e5311084b10d973d354e6925788f01e
This commit is contained in:
myasuka 2019-12-12 18:06:01 -08:00 committed by Facebook Github Bot
parent c4ce8e637f
commit 4b74035e40
4 changed files with 70 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
java/src/main/java/org/rocksdb/AdvancedMutableColumnFamilyOptionsInterface.java
View File

@ -191,7 +191,7 @@ public interface AdvancedMutableColumnFamilyOptionsInterface<
* target_file_size_multiplier is 10, then each file on level-1 will * target_file_size_multiplier is 10, then each file on level-1 will
* be 2MB, and each file on level 2 will be 20MB, * be 2MB, and each file on level 2 will be 20MB,
* and each file on level-3 will be 200MB. * and each file on level-3 will be 200MB.
* by default targetFileSizeBase is 2MB. * by default targetFileSizeBase is 64MB.
* *
* @param targetFileSizeBase the target size of a level-0 file. * @param targetFileSizeBase the target size of a level-0 file.
* @return the reference to the current options. * @return the reference to the current options.
@ -210,7 +210,7 @@ public interface AdvancedMutableColumnFamilyOptionsInterface<
* target_file_size_multiplier is 10, then each file on level-1 will * target_file_size_multiplier is 10, then each file on level-1 will
* be 2MB, and each file on level 2 will be 20MB, * be 2MB, and each file on level 2 will be 20MB,
* and each file on level-3 will be 200MB. * and each file on level-3 will be 200MB.
* by default targetFileSizeBase is 2MB. * by default targetFileSizeBase is 64MB.
* *
* @return the target size of a level-0 file. * @return the target size of a level-0 file.
* *

30
java/src/main/java/org/rocksdb/DBOptionsInterface.java
View File

@ -434,10 +434,16 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
int maxSubcompactions(); int maxSubcompactions();
/** /**
* NOT SUPPORTED ANYMORE: RocksDB automatically decides this based on the
* value of max_background_jobs. For backwards compatibility we will set
* `max_background_jobs = max_background_compactions + max_background_flushes`
* in the case where user sets at least one of `max_background_compactions` or
* `max_background_flushes`.
*
* Specifies the maximum number of concurrent background flush jobs. * Specifies the maximum number of concurrent background flush jobs.
* If you're increasing this, also consider increasing number of threads in * If you're increasing this, also consider increasing number of threads in
* HIGH priority thread pool. For more information, see * HIGH priority thread pool. For more information, see
* Default: 1 * Default: -1
* *
* @param maxBackgroundFlushes number of max concurrent flush jobs * @param maxBackgroundFlushes number of max concurrent flush jobs
* @return the instance of the current object. * @return the instance of the current object.
@ -452,10 +458,16 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
T setMaxBackgroundFlushes(int maxBackgroundFlushes); T setMaxBackgroundFlushes(int maxBackgroundFlushes);
/** /**
* NOT SUPPORTED ANYMORE: RocksDB automatically decides this based on the
* value of max_background_jobs. For backwards compatibility we will set
* `max_background_jobs = max_background_compactions + max_background_flushes`
* in the case where user sets at least one of `max_background_compactions` or
* `max_background_flushes`.
*
* Returns the maximum number of concurrent background flush jobs. * Returns the maximum number of concurrent background flush jobs.
* If you're increasing this, also consider increasing number of threads in * If you're increasing this, also consider increasing number of threads in
* HIGH priority thread pool. For more information, see * HIGH priority thread pool. For more information, see
* Default: 1 * Default: -1
* *
* @return the maximum number of concurrent background flush jobs. * @return the maximum number of concurrent background flush jobs.
* @see RocksEnv#setBackgroundThreads(int) * @see RocksEnv#setBackgroundThreads(int)
@ -569,7 +581,8 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
/** /**
* Manifest file is rolled over on reaching this limit. * Manifest file is rolled over on reaching this limit.
* The older manifest file be deleted. * The older manifest file be deleted.
* The default value is MAX_INT so that roll-over does not take place. * The default value is 1GB so that the manifest file can grow, but not
* reach the limit of storage capacity.
* *
* @param maxManifestFileSize the size limit of a manifest file. * @param maxManifestFileSize the size limit of a manifest file.
* @return the instance of the current object. * @return the instance of the current object.
@ -579,7 +592,8 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
/** /**
* Manifest file is rolled over on reaching this limit. * Manifest file is rolled over on reaching this limit.
* The older manifest file be deleted. * The older manifest file be deleted.
* The default value is MAX_INT so that roll-over does not take place. * The default value is 1GB so that the manifest file can grow, but not
* reach the limit of storage capacity.
* *
* @return the size limit of a manifest file. * @return the size limit of a manifest file.
*/ */
@ -1134,7 +1148,7 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
* It is strongly recommended to set * It is strongly recommended to set
* {@link #setEnableWriteThreadAdaptiveYield(boolean)} if you are going to use * {@link #setEnableWriteThreadAdaptiveYield(boolean)} if you are going to use
* this feature. * this feature.
* Default: false * Default: true
* *
* @param allowConcurrentMemtableWrite true to enable concurrent writes * @param allowConcurrentMemtableWrite true to enable concurrent writes
* for the memtable * for the memtable
@ -1151,7 +1165,7 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
* It is strongly recommended to set * It is strongly recommended to set
* {@link #setEnableWriteThreadAdaptiveYield(boolean)} if you are going to use * {@link #setEnableWriteThreadAdaptiveYield(boolean)} if you are going to use
* this feature. * this feature.
* Default: false * Default: true
* *
* @return true if concurrent writes are enabled for the memtable * @return true if concurrent writes are enabled for the memtable
*/ */
@ -1162,7 +1176,7 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
* wait for up to {@link #writeThreadMaxYieldUsec()} before blocking on a * wait for up to {@link #writeThreadMaxYieldUsec()} before blocking on a
* mutex. This can substantially improve throughput for concurrent workloads, * mutex. This can substantially improve throughput for concurrent workloads,
* regardless of whether {@link #allowConcurrentMemtableWrite()} is enabled. * regardless of whether {@link #allowConcurrentMemtableWrite()} is enabled.
* Default: false * Default: true
* *
* @param enableWriteThreadAdaptiveYield true to enable adaptive yield for the * @param enableWriteThreadAdaptiveYield true to enable adaptive yield for the
* write threads * write threads
@ -1177,7 +1191,7 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
* wait for up to {@link #writeThreadMaxYieldUsec()} before blocking on a * wait for up to {@link #writeThreadMaxYieldUsec()} before blocking on a
* mutex. This can substantially improve throughput for concurrent workloads, * mutex. This can substantially improve throughput for concurrent workloads,
* regardless of whether {@link #allowConcurrentMemtableWrite()} is enabled. * regardless of whether {@link #allowConcurrentMemtableWrite()} is enabled.
* Default: false * Default: true
* *
* @return true if adaptive yield is enabled * @return true if adaptive yield is enabled
* for the writing threads * for the writing threads

12
java/src/main/java/org/rocksdb/MutableColumnFamilyOptionsInterface.java
View File

@ -104,9 +104,9 @@ public interface MutableColumnFamilyOptionsInterface<
* (maxBytesForLevelBase) * (maxBytesForLevelMultiplier ^ (L-1)) * (maxBytesForLevelBase) * (maxBytesForLevelMultiplier ^ (L-1))
* For example, if maxBytesForLevelBase is 20MB, and if * For example, if maxBytesForLevelBase is 20MB, and if
* max_bytes_for_level_multiplier is 10, total data size for level-1 * max_bytes_for_level_multiplier is 10, total data size for level-1
* will be 20MB, total file size for level-2 will be 200MB, * will be 200MB, total file size for level-2 will be 2GB,
* and total file size for level-3 will be 2GB. * and total file size for level-3 will be 20GB.
* by default 'maxBytesForLevelBase' is 10MB. * by default 'maxBytesForLevelBase' is 256MB.
* *
* @param maxBytesForLevelBase maximum bytes for level base. * @param maxBytesForLevelBase maximum bytes for level base.
* *
@ -123,9 +123,9 @@ public interface MutableColumnFamilyOptionsInterface<
* (maxBytesForLevelBase) * (maxBytesForLevelMultiplier ^ (L-1)) * (maxBytesForLevelBase) * (maxBytesForLevelMultiplier ^ (L-1))
* For example, if maxBytesForLevelBase is 20MB, and if * For example, if maxBytesForLevelBase is 20MB, and if
* max_bytes_for_level_multiplier is 10, total data size for level-1 * max_bytes_for_level_multiplier is 10, total data size for level-1
* will be 20MB, total file size for level-2 will be 200MB, * will be 200MB, total file size for level-2 will be 2GB,
* and total file size for level-3 will be 2GB. * and total file size for level-3 will be 20GB.
* by default 'maxBytesForLevelBase' is 10MB. * by default 'maxBytesForLevelBase' is 256MB.
* *
* @return the upper-bound of the total size of level-1 files * @return the upper-bound of the total size of level-1 files
* in bytes. * in bytes.

47
java/src/main/java/org/rocksdb/MutableDBOptionsInterface.java
View File

@ -22,9 +22,12 @@ public interface MutableDBOptionsInterface<T extends MutableDBOptionsInterface<T
int maxBackgroundJobs(); int maxBackgroundJobs();
/** /**
* NOT SUPPORTED ANYMORE: RocksDB automatically decides this based on the
* value of max_background_jobs. This option is ignored.
*
* Suggested number of concurrent background compaction jobs, submitted to * Suggested number of concurrent background compaction jobs, submitted to
* the default LOW priority thread pool. * the default LOW priority thread pool.
* Default: 1 * Default: -1
* *
* @param baseBackgroundCompactions Suggested number of background compaction * @param baseBackgroundCompactions Suggested number of background compaction
* jobs * jobs
@ -35,20 +38,29 @@ public interface MutableDBOptionsInterface<T extends MutableDBOptionsInterface<T
void setBaseBackgroundCompactions(int baseBackgroundCompactions); void setBaseBackgroundCompactions(int baseBackgroundCompactions);
/** /**
* NOT SUPPORTED ANYMORE: RocksDB automatically decides this based on the
* value of max_background_jobs. This option is ignored.
*
* Suggested number of concurrent background compaction jobs, submitted to * Suggested number of concurrent background compaction jobs, submitted to
* the default LOW priority thread pool. * the default LOW priority thread pool.
* Default: 1 * Default: -1
* *
* @return Suggested number of background compaction jobs * @return Suggested number of background compaction jobs
*/ */
int baseBackgroundCompactions(); int baseBackgroundCompactions();
/** /**
* NOT SUPPORTED ANYMORE: RocksDB automatically decides this based on the
* value of max_background_jobs. For backwards compatibility we will set
* `max_background_jobs = max_background_compactions + max_background_flushes`
* in the case where user sets at least one of `max_background_compactions` or
* `max_background_flushes` (we replace -1 by 1 in case one option is unset).
*
* Specifies the maximum number of concurrent background compaction jobs, * Specifies the maximum number of concurrent background compaction jobs,
* submitted to the default LOW priority thread pool. * submitted to the default LOW priority thread pool.
* If you're increasing this, also consider increasing number of threads in * If you're increasing this, also consider increasing number of threads in
* LOW priority thread pool. For more information, see * LOW priority thread pool. For more information, see
* Default: 1 * Default: -1
* *
* @param maxBackgroundCompactions the maximum number of background * @param maxBackgroundCompactions the maximum number of background
* compaction jobs. * compaction jobs.
@ -57,15 +69,23 @@ public interface MutableDBOptionsInterface<T extends MutableDBOptionsInterface<T
* @see RocksEnv#setBackgroundThreads(int) * @see RocksEnv#setBackgroundThreads(int)
* @see RocksEnv#setBackgroundThreads(int, Priority) * @see RocksEnv#setBackgroundThreads(int, Priority)
* @see DBOptionsInterface#maxBackgroundFlushes() * @see DBOptionsInterface#maxBackgroundFlushes()
* @deprecated Use {@link #setMaxBackgroundJobs(int)}
*/ */
@Deprecated
T setMaxBackgroundCompactions(int maxBackgroundCompactions); T setMaxBackgroundCompactions(int maxBackgroundCompactions);
/** /**
* NOT SUPPORTED ANYMORE: RocksDB automatically decides this based on the
* value of max_background_jobs. For backwards compatibility we will set
* `max_background_jobs = max_background_compactions + max_background_flushes`
* in the case where user sets at least one of `max_background_compactions` or
* `max_background_flushes` (we replace -1 by 1 in case one option is unset).
*
* Returns the maximum number of concurrent background compaction jobs, * Returns the maximum number of concurrent background compaction jobs,
* submitted to the default LOW priority thread pool. * submitted to the default LOW priority thread pool.
* When increasing this number, we may also want to consider increasing * When increasing this number, we may also want to consider increasing
* number of threads in LOW priority thread pool. * number of threads in LOW priority thread pool.
* Default: 1 * Default: -1
* *
* @return the maximum number of concurrent background compaction jobs. * @return the maximum number of concurrent background compaction jobs.
* @see RocksEnv#setBackgroundThreads(int) * @see RocksEnv#setBackgroundThreads(int)
@ -141,10 +161,16 @@ public interface MutableDBOptionsInterface<T extends MutableDBOptionsInterface<T
* mem tables. It is calculated using size of user write requests before * mem tables. It is calculated using size of user write requests before
* compression. RocksDB may decide to slow down more if the compaction still * compression. RocksDB may decide to slow down more if the compaction still
* gets behind further. * gets behind further.
* If the value is 0, we will infer a value from `rater_limiter` value
* if it is not empty, or 16MB if `rater_limiter` is empty. Note that
* if users change the rate in `rate_limiter` after DB is opened,
* `delayed_write_rate` won't be adjusted.
* *
* Unit: bytes per second. * Unit: bytes per second.
* *
* Default: 16MB/s * Default: 0
*
* Dynamically changeable through {@link RocksDB#setDBOptions(MutableDBOptions)}.
* *
* @param delayedWriteRate the rate in bytes per second * @param delayedWriteRate the rate in bytes per second
* *
@ -160,10 +186,16 @@ public interface MutableDBOptionsInterface<T extends MutableDBOptionsInterface<T
* mem tables. It is calculated using size of user write requests before * mem tables. It is calculated using size of user write requests before
* compression. RocksDB may decide to slow down more if the compaction still * compression. RocksDB may decide to slow down more if the compaction still
* gets behind further. * gets behind further.
* If the value is 0, we will infer a value from `rater_limiter` value
* if it is not empty, or 16MB if `rater_limiter` is empty. Note that
* if users change the rate in `rate_limiter` after DB is opened,
* `delayed_write_rate` won't be adjusted.
* *
* Unit: bytes per second. * Unit: bytes per second.
* *
* Default: 16MB/s * Default: 0
*
* Dynamically changeable through {@link RocksDB#setDBOptions(MutableDBOptions)}.
* *
* @return the rate in bytes per second * @return the rate in bytes per second
*/ */
@ -282,7 +314,7 @@ public interface MutableDBOptionsInterface<T extends MutableDBOptionsInterface<T
* on {@code target_file_size_base} and {@code target_file_size_multiplier} * on {@code target_file_size_base} and {@code target_file_size_multiplier}
* for level-based compaction. For universal-style compaction, you can usually * for level-based compaction. For universal-style compaction, you can usually
* set it to -1. * set it to -1.
* Default: 5000 * Default: -1
* *
* @param maxOpenFiles the maximum number of open files. * @param maxOpenFiles the maximum number of open files.
* @return the instance of the current object. * @return the instance of the current object.
@ -296,6 +328,7 @@ public interface MutableDBOptionsInterface<T extends MutableDBOptionsInterface<T
* on {@code target_file_size_base} and {@code target_file_size_multiplier} * on {@code target_file_size_base} and {@code target_file_size_multiplier}
* for level-based compaction. For universal-style compaction, you can usually * for level-based compaction. For universal-style compaction, you can usually
* set it to -1. * set it to -1.
* Default: -1
* *
* @return the maximum number of open files. * @return the maximum number of open files.
*/ */