Correct java docs of RocksDB options (#6123)

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

java/src/main/java/org/rocksdb/AdvancedMutableColumnFamilyOptionsInterface.java

@@ -191,7 +191,7 @@ public interface AdvancedMutableColumnFamilyOptionsInterface<
    * target_file_size_multiplier is 10, then each file on level-1 will
    * be 2MB, and each file on level 2 will be 20MB,
    * 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.
    * @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
    * be 2MB, and each file on level 2 will be 20MB,
    * 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.
    *

java/src/main/java/org/rocksdb/DBOptionsInterface.java

@@ -434,10 +434,16 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
   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.
    * If you're increasing this, also consider increasing number of threads in
    * HIGH priority thread pool. For more information, see
-   * Default: 1
+   * Default: -1
    *
    * @param maxBackgroundFlushes number of max concurrent flush jobs
    * @return the instance of the current object.
@@ -452,10 +458,16 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
   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.
    * If you're increasing this, also consider increasing number of threads in
    * HIGH priority thread pool. For more information, see
-   * Default: 1
+   * Default: -1
    *
    * @return the maximum number of concurrent background flush jobs.
    * @see RocksEnv#setBackgroundThreads(int)
@@ -569,7 +581,8 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
   /**
    * Manifest file is rolled over on reaching this limit.
    * 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.
    * @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.
    * 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.
    */
@@ -1134,7 +1148,7 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
    * It is strongly recommended to set
    * {@link #setEnableWriteThreadAdaptiveYield(boolean)} if you are going to use
    * this feature.
-   * Default: false
+   * Default: true
    *
    * @param allowConcurrentMemtableWrite true to enable concurrent writes
    *     for the memtable
@@ -1151,7 +1165,7 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
    * It is strongly recommended to set
    * {@link #setEnableWriteThreadAdaptiveYield(boolean)} if you are going to use
    * this feature.
-   * Default: false
+   * Default: true
    *
    * @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
    * mutex. This can substantially improve throughput for concurrent workloads,
    * regardless of whether {@link #allowConcurrentMemtableWrite()} is enabled.
-   * Default: false
+   * Default: true
    *
    * @param enableWriteThreadAdaptiveYield true to enable adaptive yield for the
    *     write threads
@@ -1177,7 +1191,7 @@ public interface DBOptionsInterface<T extends DBOptionsInterface<T>> {
    * wait for up to {@link #writeThreadMaxYieldUsec()} before blocking on a
    * mutex. This can substantially improve throughput for concurrent workloads,
    * regardless of whether {@link #allowConcurrentMemtableWrite()} is enabled.
-   * Default: false
+   * Default: true
    *
    * @return true if adaptive yield is enabled
    *    for the writing threads

java/src/main/java/org/rocksdb/MutableColumnFamilyOptionsInterface.java

@@ -104,9 +104,9 @@ public interface MutableColumnFamilyOptionsInterface<
    * (maxBytesForLevelBase) * (maxBytesForLevelMultiplier ^ (L-1))
    * For example, if maxBytesForLevelBase is 20MB, and if
    * 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.
    *
@@ -123,9 +123,9 @@ public interface MutableColumnFamilyOptionsInterface<
    * (maxBytesForLevelBase) * (maxBytesForLevelMultiplier ^ (L-1))
    * For example, if maxBytesForLevelBase is 20MB, and if
    * 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
    *     in bytes.

java/src/main/java/org/rocksdb/MutableDBOptionsInterface.java

@@ -22,9 +22,12 @@ public interface MutableDBOptionsInterface<T extends MutableDBOptionsInterface<T
   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
    * the default LOW priority thread pool.
-   * Default: 1
+   * Default: -1
    *
    * @param baseBackgroundCompactions Suggested number of background compaction
    *     jobs
@@ -35,20 +38,29 @@ public interface MutableDBOptionsInterface<T extends MutableDBOptionsInterface<T
   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
    * the default LOW priority thread pool.
-   * Default: 1
+   * Default: -1
    *
    * @return Suggested number of background compaction jobs
    */
   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,
    * submitted to the default LOW priority thread pool.
    * If you're increasing this, also consider increasing number of threads in
    * LOW priority thread pool. For more information, see
-   * Default: 1
+   * Default: -1
    *
    * @param maxBackgroundCompactions the maximum number of background
    *     compaction jobs.
@@ -57,15 +69,23 @@ public interface MutableDBOptionsInterface<T extends MutableDBOptionsInterface<T
    * @see RocksEnv#setBackgroundThreads(int)
    * @see RocksEnv#setBackgroundThreads(int, Priority)
    * @see DBOptionsInterface#maxBackgroundFlushes()
+   * @deprecated Use {@link #setMaxBackgroundJobs(int)}
    */
+  @Deprecated
   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,
    * submitted to the default LOW priority thread pool.
    * When increasing this number, we may also want to consider increasing
    * number of threads in LOW priority thread pool.
-   * Default: 1
+   * Default: -1
    *
    * @return the maximum number of concurrent background compaction jobs.
    * @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
    * compression. RocksDB may decide to slow down more if the compaction still
    * 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.
    *
-   * Default: 16MB/s
+   * Default: 0
+   *
+   * Dynamically changeable through {@link RocksDB#setDBOptions(MutableDBOptions)}.
    *
    * @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
    * compression. RocksDB may decide to slow down more if the compaction still
    * 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.
    *
-   * Default: 16MB/s
+   * Default: 0
+   *
+   * Dynamically changeable through {@link RocksDB#setDBOptions(MutableDBOptions)}.
    *
    * @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}
    * for level-based compaction. For universal-style compaction, you can usually
    * set it to -1.
-   * Default: 5000
+   * Default: -1
    *
    * @param maxOpenFiles the maximum number of open files.
    * @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}
    * for level-based compaction. For universal-style compaction, you can usually
    * set it to -1.
+   * Default: -1
    *
    * @return the maximum number of open files.
    */