feat: defer persist every N commits

Author: RodrigoVillar

ffi/firewood.go

@@ -62,7 +62,8 @@ var (
 	// ErrActiveKeepAliveHandles is returned when attempting to close a database with unfreed memory.
 	ErrActiveKeepAliveHandles = errors.New("cannot close database with active keep-alive handles")
 
-	errDBClosed = errors.New("firewood database already closed")
+	errDBClosed        = errors.New("firewood database already closed")
+	errZeroCommitCount = errors.New("deferred persistence commit count must not be 0")
 )
 
 // Database is an FFI wrapper for the Rust Firewood database.
@@ -113,14 +114,18 @@ type config struct {
 	rootStore bool
 	// expensiveMetricsEnabled controls whether expensive metrics recording is enabled.
 	expensiveMetricsEnabled bool
+	// deferredPersistenceCommitCount determines the maximum number of unpersisted
+	// revisions that can exist at a given time.
+	deferredPersistenceCommitCount uint64
 }
 
 func defaultConfig() *config {
 	return &config{
-		nodeCacheEntries:     1_000_000,
-		freeListCacheEntries: 1_000_000,
-		revisions:            100,
-		readCacheStrategy:    OnlyCacheWrites,
+		nodeCacheEntries:               1_000_000,
+		freeListCacheEntries:           1_000_000,
+		revisions:                      100,
+		readCacheStrategy:              OnlyCacheWrites,
+		deferredPersistenceCommitCount: 1,
 	}
 }
 
@@ -193,6 +198,15 @@ func WithExpensiveMetrics() Option {
 	}
 }
 
+// WithDeferredPersistenceCommitCount sets the maximum number of unpersisted revisions
+// that can exist at a time. Note: `commitCount` must be greater than 0.
+// Default: 1
+func WithDeferredPersistenceCommitCount(commitCount uint64) Option {
+	return func(c *config) {
+		c.deferredPersistenceCommitCount = commitCount
+	}
+}
+
 // A CacheStrategy represents the caching strategy used by a [Database].
 type CacheStrategy uint8
 
@@ -245,20 +259,24 @@ func New(dbDir string, nodeHashAlgorithm NodeHashAlgorithm, opts ...Option) (*Da
 	if conf.freeListCacheEntries < 1 {
 		return nil, fmt.Errorf("free list cache entries must be >= 1, got %d", conf.freeListCacheEntries)
 	}
+	if conf.deferredPersistenceCommitCount == 0 {
+		return nil, errZeroCommitCount
+	}
 
 	var pinner runtime.Pinner
 	defer pinner.Unpin()
 
 	args := C.struct_DatabaseHandleArgs{
-		dir:                  newBorrowedBytes([]byte(dbDir), &pinner),
-		cache_size:           C.size_t(conf.nodeCacheEntries),
-		free_list_cache_size: C.size_t(conf.freeListCacheEntries),
-		revisions:            C.size_t(conf.revisions),
-		strategy:             C.uint8_t(conf.readCacheStrategy),
-		truncate:             C.bool(conf.truncate),
-		root_store:           C.bool(conf.rootStore),
-		expensive_metrics:    C.bool(conf.expensiveMetricsEnabled),
-		node_hash_algorithm:  C.enum_NodeHashAlgorithm(nodeHashAlgorithm),
+		dir:                               newBorrowedBytes([]byte(dbDir), &pinner),
+		cache_size:                        C.size_t(conf.nodeCacheEntries),
+		free_list_cache_size:              C.size_t(conf.freeListCacheEntries),
+		revisions:                         C.size_t(conf.revisions),
+		strategy:                          C.uint8_t(conf.readCacheStrategy),
+		truncate:                          C.bool(conf.truncate),
+		root_store:                        C.bool(conf.rootStore),
+		expensive_metrics:                 C.bool(conf.expensiveMetricsEnabled),
+		node_hash_algorithm:               C.enum_NodeHashAlgorithm(nodeHashAlgorithm),
+		deferred_persistence_commit_count: C.uint64_t(conf.deferredPersistenceCommitCount),
 	}
 
 	return getDatabaseFromHandleResult(C.fwd_open_db(args))

ffi/firewood.h

@@ -1,7 +1,7 @@
 // Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
 // See the file LICENSE.md for licensing terms.
 
-use std::num::NonZeroUsize;
+use std::num::{NonZeroU64, NonZeroUsize};
 
 use firewood::{
     db::{Db, DbConfig},
@@ -99,6 +99,9 @@ pub struct DatabaseHandleArgs<'a> {
     ///
     /// Opening returns an error if this does not match the compile-time feature.
     pub node_hash_algorithm: NodeHashAlgorithm,
+
+    /// The maximum number of unpersisted revisions that can exist at a given time.
+    pub deferred_persistence_commit_count: u64,
 }
 
 impl DatabaseHandleArgs<'_> {
@@ -152,12 +155,15 @@ impl DatabaseHandle {
     /// If the path is empty, or if the configuration is invalid, this will return an error.
     pub fn new(args: DatabaseHandleArgs<'_>) -> Result<Self, api::Error> {
         let metrics_context = MetricsContext::new(args.expensive_metrics);
+        let commit_count = NonZeroU64::new(args.deferred_persistence_commit_count)
+            .ok_or(api::Error::ZeroCommitCount)?;
 
         let cfg = DbConfig::builder()
             .node_hash_algorithm(args.node_hash_algorithm.into())
             .truncate(args.truncate)
             .manager(args.as_rev_manager_config()?)
             .root_store(args.root_store)
+            .deferred_persistence_commit_count(commit_count)
             .build();
 
         let path = args