Add async WAL precreation

Summary:
- Add experimental immutable `DBOptions::async_wal_precreate` to reserve and open one future WAL on a background HIGH-priority task, with sanitization that disables the optimization when WAL recycling is configured.
- Split WAL creation into open/preallocate and start phases so `SwitchMemtable()` can consume a prepared WAL after writing normal WAL metadata, wait for in-flight precreation, fall back to synchronous creation, and delete an unstarted prepared WAL on start failure.
- Keep WAL numbering, close, recovery, and read-only open safe for empty future WAL files left by async precreation; `error_if_wal_file_exists=true` now rejects non-empty WALs while tolerating empty WALs.
- Add public option plumbing for the C API, options parsing/stringification, random option testing, `db_bench`, `db_stress`, and crash-test configuration.
- Add WAL precreate statistics counters plus Java `TickerType`/JNI mappings, and update C++, C, and Java read-only-open documentation for the empty-WAL behavior.
- Add focused WAL/option/C/Java tests for async precreate ready/wait/failure/recovery paths, read-only WAL detection, option sanitization, and API plumbing, plus write-flow docs and unreleased history entries for the new feature and behavior change.

PR https://github.com/facebook/rocksdb/pull/14738

Reviewed By: pdillinger

Differential Revision: D105020559

fbshipit-source-id: 5059b424702e021abb8de65ceeb6d3b975280ffc

java/rocksjni/portal.h

@@ -5011,6 +5011,16 @@ class TickerTypeJni {
         return 0x53;
       case ROCKSDB_NAMESPACE::Tickers::WAL_FILE_BYTES:
         return 0x54;
+      case ROCKSDB_NAMESPACE::Tickers::WAL_PRECREATE_HIT:
+        return -0x6C;
+      case ROCKSDB_NAMESPACE::Tickers::WAL_PRECREATE_MISS:
+        return -0x6D;
+      case ROCKSDB_NAMESPACE::Tickers::WAL_PRECREATE_WAITED:
+        return -0x6E;
+      case ROCKSDB_NAMESPACE::Tickers::WAL_PRECREATE_WAIT_MICROS:
+        return -0x6F;
+      case ROCKSDB_NAMESPACE::Tickers::WAL_PRECREATE_FAILED:
+        return -0x70;
       case ROCKSDB_NAMESPACE::Tickers::WRITE_DONE_BY_SELF:
         return 0x55;
       case ROCKSDB_NAMESPACE::Tickers::WRITE_DONE_BY_OTHER:
@@ -5509,6 +5519,16 @@ class TickerTypeJni {
         return ROCKSDB_NAMESPACE::Tickers::WAL_FILE_SYNCED;
       case 0x54:
         return ROCKSDB_NAMESPACE::Tickers::WAL_FILE_BYTES;
+      case -0x6C:
+        return ROCKSDB_NAMESPACE::Tickers::WAL_PRECREATE_HIT;
+      case -0x6D:
+        return ROCKSDB_NAMESPACE::Tickers::WAL_PRECREATE_MISS;
+      case -0x6E:
+        return ROCKSDB_NAMESPACE::Tickers::WAL_PRECREATE_WAITED;
+      case -0x6F:
+        return ROCKSDB_NAMESPACE::Tickers::WAL_PRECREATE_WAIT_MICROS;
+      case -0x70:
+        return ROCKSDB_NAMESPACE::Tickers::WAL_PRECREATE_FAILED;
       case 0x55:
         return ROCKSDB_NAMESPACE::Tickers::WRITE_DONE_BY_SELF;
       case 0x56:

java/src/main/java/org/rocksdb/RocksDB.java

@@ -404,7 +404,7 @@ public class RocksDB extends RocksObject {
    * @param options {@link Options} instance.
    * @param path the path to the RocksDB.
    * @param errorIfWalFileExists true to raise an error when opening the db
-   *            if a Write Ahead Log file exists, false otherwise.
+   *            if a non-empty Write Ahead Log file exists, false otherwise.
    * @return a {@link RocksDB} instance on success, null if the specified
    *     {@link RocksDB} can not be opened.
    *
@@ -493,7 +493,7 @@ public class RocksDB extends RocksObject {
    * @param columnFamilyHandles will be filled with ColumnFamilyHandle instances
    *     on open.
    * @param errorIfWalFileExists true to raise an error when opening the db
-   *            if a Write Ahead Log file exists, false otherwise.
+   *            if a non-empty Write Ahead Log file exists, false otherwise.
    * @return a {@link RocksDB} instance on success, null if the specified
    *     {@link RocksDB} can not be opened.
    *

java/src/main/java/org/rocksdb/TickerType.java

@@ -394,6 +394,31 @@ public enum TickerType {
      */
     WAL_FILE_BYTES((byte) 0x54),
 
+    /**
+     * Number of WAL rotations that consumed an async precreated WAL.
+     */
+    WAL_PRECREATE_HIT((byte) -0x6C),
+
+    /**
+     * Number of WAL rotations that found no async precreated WAL to consume.
+     */
+    WAL_PRECREATE_MISS((byte) -0x6D),
+
+    /**
+     * Number of WAL rotations that waited for an in-flight WAL precreation.
+     */
+    WAL_PRECREATE_WAITED((byte) -0x6E),
+
+    /**
+     * Total foreground wait time for in-flight WAL precreation.
+     */
+    WAL_PRECREATE_WAIT_MICROS((byte) -0x6F),
+
+    /**
+     * Number of async WAL precreation attempts that failed.
+     */
+    WAL_PRECREATE_FAILED((byte) -0x70),
+
     /**
      * Writes can be processed by requesting thread or by the thread at the
      * head of the writers queue.

java/src/test/java/org/rocksdb/ReadOnlyTest.java

@@ -6,6 +6,8 @@ package org.rocksdb;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+import java.io.IOException;
+import java.nio.file.Files;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
@@ -200,11 +202,12 @@ public class ReadOnlyTest {
   }
 
   @Test(expected = RocksDBException.class)
-  public void errorIfWalFileExists() throws RocksDBException {
+  public void errorIfWalFileExists() throws RocksDBException, IOException {
     try (final Options options = new Options().setCreateIfMissing(true);
          final RocksDB ignored = RocksDB.open(options, dbFolder.getRoot().getAbsolutePath())) {
       // no-op
     }
+    Files.write(dbFolder.getRoot().toPath().resolve("999999.log"), new byte[] {1});
 
     try (final ColumnFamilyOptions cfOpts = new ColumnFamilyOptions()) {
       final List<ColumnFamilyDescriptor> cfDescriptors = Collections.singletonList(