New scheme for managing writeback (and completion)

Makefile

@@ -83,6 +83,11 @@ CFLAGS += -DSPLINTERDB_PLATFORM_DIR=$(PLATFORM_DIR)
 GIT_VERSION := "$(shell git describe --abbrev=8 --dirty --always --tags)"
 GIT_VERSION_CFLAGS += -DGIT_VERSION=\"$(GIT_VERSION)\"
 
+# Fix annoying warning about avx-256 vs avx-512
+ifeq "$(findstring clang, $(CC))" "clang"
+   CFLAGS += -Wno-invalid-feature-combination
+endif
+
 cpu_arch := $(shell uname -p)
 ifeq ($(cpu_arch),x86_64)
   # not supported on ARM64
@@ -427,11 +432,12 @@ PLATFORM_IO_SYS = $(OBJDIR)/$(SRCDIR)/$(PLATFORM_DIR)/platform_io.o \
 
 UTIL_SYS = $(OBJDIR)/$(SRCDIR)/util.o $(PLATFORM_SYS)
 
-CLOCKCACHE_SYS = $(OBJDIR)/$(SRCDIR)/clockcache.o	  \
-                 $(OBJDIR)/$(SRCDIR)/allocator.o    \
-                 $(OBJDIR)/$(SRCDIR)/rc_allocator.o \
-                 $(OBJDIR)/$(SRCDIR)/task.o         \
-                 $(UTIL_SYS)                        \
+CLOCKCACHE_SYS = $(OBJDIR)/$(SRCDIR)/clockcache.o	    \
+                 $(OBJDIR)/$(SRCDIR)/allocator.o      \
+                 $(OBJDIR)/$(SRCDIR)/rc_allocator.o   \
+                 $(OBJDIR)/$(SRCDIR)/task.o           \
+                 $(OBJDIR)/$(SRCDIR)/writeback_set.o  \
+                 $(UTIL_SYS)                          \
                  $(PLATFORM_IO_SYS)
 
 BTREE_SYS = $(OBJDIR)/$(SRCDIR)/btree.o           \
@@ -468,6 +474,14 @@ $(BINDIR)/$(UNITDIR)/btree_stress_test: $(OBJDIR)/$(UNIT_TESTSDIR)/btree_test_co
                                         $(COMMON_UNIT_TESTOBJ)                          \
                                         $(BTREE_SYS)
 
+# Uses btree_test_common only for its init_*_config_from_master_config()
+# helpers, which is why it pulls BTREE_SYS rather than just CLOCKCACHE_SYS.
+$(BINDIR)/$(UNITDIR)/writeback_set_test: $(OBJDIR)/$(UNIT_TESTSDIR)/btree_test_common.o \
+                                         $(OBJDIR)/$(TESTS_DIR)/config.o                \
+                                         $(OBJDIR)/$(TESTS_DIR)/test_data.o             \
+                                         $(COMMON_UNIT_TESTOBJ)                         \
+                                         $(BTREE_SYS)
+
 $(BINDIR)/$(UNITDIR)/splinter_test: $(COMMON_TESTOBJ)                             \
                                     $(COMMON_UNIT_TESTOBJ)                        \
                                     $(OBJDIR)/$(FUNCTIONAL_TESTSDIR)/test_async.o \
@@ -548,6 +562,7 @@ unit/misc_test:                    $(BINDIR)/$(UNITDIR)/misc_test
 unit/platform_threads_test:        $(BINDIR)/$(UNITDIR)/platform_threads_test
 unit/btree_test:                   $(BINDIR)/$(UNITDIR)/btree_test
 unit/btree_stress_test:            $(BINDIR)/$(UNITDIR)/btree_stress_test
+unit/writeback_set_test:           $(BINDIR)/$(UNITDIR)/writeback_set_test
 unit/splinter_test:                $(BINDIR)/$(UNITDIR)/splinter_test
 unit/splinterdb_quick_test:        $(BINDIR)/$(UNITDIR)/splinterdb_quick_test
 unit/splinterdb_stress_test:       $(BINDIR)/$(UNITDIR)/splinterdb_stress_test

docs/limitations.md

@@ -9,7 +9,6 @@ Thus, SplinterDB is provided *as-is* given the following limitations and missing
 * SplinterDB on-disk format is not versioned (Data may not survive software upgrades.)
 * Single 4KiB page size, with fixed extent size of 32 pages/extent.
 * Key and value size need to be less than the page size.
-* SplinterDB does not expose an API to force the latest write to be durable (e.g., fsync/commit.)
 * SplinterDB disk size cannot be changed once configured.
 * SplinterDB does not have a public API for the experimental async features.
 * SplinterDB does not retain configuration parameters and metadata. (These cannot

docs/site/content/docs/limitations.md

@@ -12,7 +12,6 @@ Thus, SplinterDB is provided *as-is* given the following limitations and missing
   between 8 to 105 bytes. Support for smaller key-sizes is experimental.
 * The application must specify the minimum and maximum of the key range.
 * SplinterDB on-disk size is fixed at compile time.
-* SplinterDB does not expose an API to force the latest write to be durable (e.g., fsync/commit.)
 * SplinterDB disk size cannot be changed once configured.
 * SplinterDB does not have a public API for the experimental async features.
 * SplinterDB does not retain configuration parameters and metadata. (These cannot

examples/splinterdb_custom_ipv4_addr_sortcmp_example.c

@@ -172,7 +172,7 @@ main()
    start_key = "100.101.102.103";
    do_iterate_from(spl_handle, start_key);
 
-   splinterdb_close(&spl_handle);
+   splinterdb_close(&spl_handle, FALSE);
    printf("Shutdown SplinterDB instance, dbname '%s'.\n\n", DB_FILE_NAME);
 
    return rc;

examples/splinterdb_intro_example.c

@@ -94,7 +94,13 @@ main()
    printf("\n");
 
    printf("Shutdown and reopen SplinterDB instance ...\n");
-   splinterdb_close(&spl_handle);
+   rc = splinterdb_close(&spl_handle, FALSE);
+   if (rc) {
+      printf("Error shutting down SplinterDB instance, dbname '%s' (rc=%d).\n",
+             DB_FILE_NAME,
+             rc);
+      return rc;
+   }
 
    rc = splinterdb_open(&splinterdb_cfg, &spl_handle);
    if (rc) {
@@ -129,7 +135,7 @@ main()
 
    printf("Found %d key-value pairs\n\n", i);
 
-   splinterdb_close(&spl_handle);
+   splinterdb_close(&spl_handle, FALSE);
    printf("Shutdown SplinterDB instance, dbname '%s'.\n\n", DB_FILE_NAME);
 
    return rc;

examples/splinterdb_iterators_example.c

@@ -90,7 +90,7 @@ main()
    start_key = "www.twitter.com";
    do_iterate_from(spl_handle, start_key);
 
-   splinterdb_close(&spl_handle);
+   splinterdb_close(&spl_handle, FALSE);
    printf("Shutdown SplinterDB instance, dbname '%s'.\n\n", DB_FILE_NAME);
 
    return rc;

examples/splinterdb_optimize_example.c

@@ -109,7 +109,7 @@ main(int argc, char **argv)
       fprintf(stderr, "splinterdb_optimize failed: %d\n", rc);
    }
 
-   splinterdb_close(&spl);
+   splinterdb_close(&spl, FALSE);
    return rc;
 }
 

examples/splinterdb_wide_values_example.c

@@ -111,7 +111,7 @@ main()
    }
    splinterdb_lookup_result_deinit(&result);
 
-   splinterdb_close(&spl_handle);
+   splinterdb_close(&spl_handle, FALSE);
    printf("Shutdown SplinterDB instance, dbname '%s'.\n\n", DB_FILE_NAME);
 
    return rc;

include/splinterdb/splinterdb.h

@@ -102,9 +102,10 @@ typedef struct splinterdb_config {
    _Bool use_log;
 
    // Automatic checkpoints: once the write-ahead log has grown by this many
-   // bytes, SplinterDB takes a checkpoint, which folds the logged updates into
-   // the durable tree and reclaims that log's space.  This bounds both how much
-   // log a crash has to replay and how much space the log occupies.
+   // bytes, SplinterDB arms a checkpoint.  The next natural memtable rotation
+   // cuts the log, after which the checkpoint folds the logged updates into the
+   // durable tree and reclaims that log's space.  This bounds both how much log
+   // a crash has to replay and how much space the log occupies.
    //
    // The trigger is sized in log bytes rather than in updates because the two
    // are independent: a workload that repeatedly overwrites the same keys grows
@@ -117,6 +118,13 @@ typedef struct splinterdb_config {
    // very large (UINT64_MAX).
    uint64 checkpoint_log_size_bytes;
 
+   // Once an automatic checkpoint is armed, allow the live log to grow by this
+   // many additional bytes while waiting for a natural memtable rotation.  If
+   // the memtable has not rotated by then, SplinterDB forces a rotation.  Zero
+   // selects a default of twice the memtable capacity; UINT64_MAX effectively
+   // disables forced rotation while retaining the soft checkpoint trigger.
+   uint64 checkpoint_log_grace_bytes;
+
    // splinter
    uint64 memtable_capacity;
    uint64 fanout;
@@ -205,9 +213,30 @@ splinterdb_open(const splinterdb_config *cfg, splinterdb **kvs);
 
 // Close a splinterdb
 //
-// This will flush all data to disk and release all resources
-void
-splinterdb_close(splinterdb **kvs);
+// A completed close makes all acknowledged data recoverable and releases all
+// resources.
+//
+// STATUS_OK means all acknowledged data is recoverable.  Recovery may still
+// need to replay a durable log or rebuild allocator state; that is not a close
+// failure.
+//
+// Without force, any error means shutdown was refused before destructive
+// teardown.  The database remains open and *kvs is unchanged, so the caller can
+// retry or investigate.
+//
+// With force, teardown always completes.  An error means data preservation
+// could not be guaranteed; it does not prove that data was actually lost.
+//
+// force | return code | database closed? | meaning
+// ---------------------------------------------------------------
+// FALSE | STATUS_OK   | YES              | acknowledged data is recoverable
+// FALSE | any error   | NO               | shutdown was refused
+// TRUE  | STATUS_OK   | YES              | acknowledged data is recoverable
+// TRUE  | any error   | YES              | preservation cannot be guaranteed
+//
+// After STATUS_OK or any forced close, *kvs is freed and set to NULL.
+int
+splinterdb_close(splinterdb **kvs, bool32 force);
 
 
 ////////////////////////////////////
@@ -333,6 +362,9 @@ splinterdb_lookup(splinterdb               *kvs,   // IN
 // Updates
 /////////////////////////////////
 
+// A successful update is visible to subsequent operations, but is not
+// necessarily durable. Use splinterdb_durable_barrier() to establish crash
+// durability for a prefix of updates.
 
 // Insert a key and value.  Overwrites any previous value associated with the
 // key.
@@ -372,6 +404,29 @@ splinterdb_optimize(splinterdb              *kvs,
                     _Bool                    full_leaf_compactions,
                     splinterdb_notification *notification);
 
+/////////////////////////////////
+// Durability
+/////////////////////////////////
+
+// Establish a durability barrier.
+//
+// On success, every update to kvs that linearized before this call began is
+// recoverable after a crash or power loss. This includes every successful
+// insert, update, or delete that returned before the call began. Updates may
+// proceed concurrently; an update overlapping the call may or may not be
+// covered.
+//
+// This establishes durability only. With the write-ahead log enabled, it does
+// not promise a checkpoint, log reclamation, a clean cache, or recovery without
+// log replay. Without the write-ahead log, SplinterDB obtains the same
+// guarantee by checkpointing the tree, which may be substantially more
+// expensive.
+//
+// Returns 0 on success. A nonzero return means the guarantee was not
+// established; some or all updates may nevertheless already be durable.
+int
+splinterdb_durable_barrier(splinterdb *kvs);
+
 /*
 Iterator API (range query)
 

src/allocator.h

@@ -235,6 +235,19 @@ allocator_get_refcount(allocator *al, uint64 addr)
    return al->ops->get_ref(al, addr);
 }
 
+/*
+ * Discard whatever the refcount map holds and start a rebuild: afterwards only
+ * the reserved extents are referenced, and
+ * allocator_recovery_record_reference() supplies the rest until
+ * allocator_recovery_finish() declares the map usable.
+ *
+ * Repeatable, deliberately.  Crash recovery rebuilds twice: once counting the
+ * logs, so that replay is never handed an extent a record it has not reached
+ * yet depends on, and again from the durable root alone once replay has
+ * finished and been folded in.  The second rebuild is what frees the logs --
+ * their extents are simply absent from it -- which is why nothing has to
+ * enumerate them a second time in order to release them.
+ */
 static inline platform_status
 allocator_recovery_begin(allocator *al)
 {