Make compactor check interval and initial delay configurable

db.go

@@ -147,6 +147,12 @@ func checkAndSetOptions(opt *Options) error {
 	if opt.NumCompactors == 1 {
 		return errors.New("Cannot have 1 compactor. Need at least 2")
 	}
+	if opt.CompactorCheckInterval < 0 {
+		return errors.New("CompactorCheckInterval cannot be negative")
+	}
+	if opt.CompactorInitialDelay < 0 {
+		return errors.New("CompactorInitialDelay cannot be negative")
+	}
 
 	if opt.InMemory && (opt.Dir != "" || opt.ValueDir != "") {
 		return errors.New("Cannot use badger in Disk-less mode with Dir or ValueDir set")

levels.go

@@ -478,14 +478,46 @@ func (s *levelsController) levelTargets() targets {
 	return t
 }
 
+const (
+	defaultCompactorCheckInterval = 50 * time.Millisecond
+	compactorLmaxInterval         = 10 * time.Second
+)
+
+func (opt Options) compactorCheckInterval() time.Duration {
+	if opt.CompactorCheckInterval > 0 {
+		return opt.CompactorCheckInterval
+	}
+	return defaultCompactorCheckInterval
+}
+
+func (opt Options) compactorInitialDelay() time.Duration {
+	if opt.CompactorInitialDelay > 0 {
+		return opt.CompactorInitialDelay
+	}
+	// Preserve the historical startup behavior: stagger each compactor by a
+	// random delay in [0, 1s).
+	return time.Duration(rand.Int31n(1000)) * time.Millisecond
+}
+
+func compactorLmaxTicks(checkInterval time.Duration) int {
+	if checkInterval <= 0 {
+		checkInterval = defaultCompactorCheckInterval
+	}
+	ticks := int((compactorLmaxInterval + checkInterval - 1) / checkInterval)
+	if ticks < 1 {
+		return 1
+	}
+	return ticks
+}
+
 func (s *levelsController) runCompactor(id int, lc *z.Closer) {
 	defer lc.Done()
 
-	randomDelay := time.NewTimer(time.Duration(rand.Int31n(1000)) * time.Millisecond)
+	initialDelay := time.NewTimer(s.kv.opt.compactorInitialDelay())
 	select {
-	case <-randomDelay.C:
+	case <-initialDelay.C:
 	case <-lc.HasBeenClosed():
-		randomDelay.Stop()
+		initialDelay.Stop()
 		return
 	}
 
@@ -554,15 +586,18 @@ func (s *levelsController) runCompactor(id int, lc *z.Closer) {
 
 	}
 	count := 0
-	ticker := time.NewTicker(50 * time.Millisecond)
+	checkInterval := s.kv.opt.compactorCheckInterval()
+	lmaxTicks := compactorLmaxTicks(checkInterval)
+	ticker := time.NewTicker(checkInterval)
 	defer ticker.Stop()
 	for {
 		select {
 		// Can add a done channel or other stuff.
 		case <-ticker.C:
 			count++
-			// Each ticker is 50ms so 50*200=10seconds.
-			if s.kv.opt.LmaxCompaction && id == 2 && count >= 200 {
+			// Attempt Lmax-to-Lmax compaction approximately every 10 seconds,
+			// regardless of the configured compactor check interval.
+			if s.kv.opt.LmaxCompaction && id == 2 && count >= lmaxTicks {
 				tryLmaxToLmaxCompaction()
 				count = 0
 			} else {

options.go

@@ -78,6 +78,9 @@ type Options struct {
 	LmaxCompaction       bool
 	ZSTDCompressionLevel int
 
+	CompactorCheckInterval time.Duration
+	CompactorInitialDelay  time.Duration
+
 	// When set, checksum will be validated for each entry read from the value log file.
 	VerifyValueChecksum bool
 
@@ -134,7 +137,11 @@ func DefaultOptions(path string) Options {
 		NumGoroutines:       8,
 		MetricsEnabled:      true,
 
-		NumCompactors:           4, // Run at least 2 compactors. Zero-th compactor prioritizes L0.
+		NumCompactors:          4, // Run at least 2 compactors. Zero-th compactor prioritizes L0.
+		CompactorCheckInterval: defaultCompactorCheckInterval,
+		// CompactorInitialDelay is intentionally zero: zero preserves the
+		// legacy behavior of staggering each compactor by a random delay
+		// of less than one second.
 		NumLevelZeroTables:      5,
 		NumLevelZeroTablesStall: 15,
 		NumMemtables:            5,
@@ -618,6 +625,30 @@ func (opt Options) WithCompactL0OnClose(val bool) Options {
 	return opt
 }
 
+// WithCompactorCheckInterval sets how often each compactor wakes up to look
+// for compaction work. Longer intervals reduce idle CPU usage but can delay
+// compaction after new tables are added.
+//
+// The default value of CompactorCheckInterval is 50 milliseconds. A zero
+// value also selects the default. Negative values are rejected by Open.
+func (opt Options) WithCompactorCheckInterval(val time.Duration) Options {
+	opt.CompactorCheckInterval = val
+	return opt
+}
+
+// WithCompactorInitialDelay sets how long each compactor waits before it
+// first checks for compaction work.
+//
+// The default value of CompactorInitialDelay is zero. Zero does not mean
+// that every compactor starts immediately: it preserves Badger's existing
+// behavior of staggering each compactor by a random delay of less than one
+// second. A positive value uses that exact delay for every compactor.
+// Negative values are rejected by Open.
+func (opt Options) WithCompactorInitialDelay(val time.Duration) Options {
+	opt.CompactorInitialDelay = val
+	return opt
+}
+
 // WithEncryptionKey is used to encrypt the data with AES. Type of AES is used based on the key
 // size. For example 16 bytes will use AES-128. 24 bytes will use AES-192. 32 bytes will
 // use AES-256.

options_test.go

@@ -8,6 +8,7 @@ package badger
 import (
 	"reflect"
 	"testing"
+	"time"
 
 	"github.com/dgraph-io/badger/v4/options"
 )
@@ -47,6 +48,69 @@ func TestOptions(t *testing.T) {
 	})
 }
 
+func TestCompactorSchedulingOptions(t *testing.T) {
+	def := DefaultOptions("")
+	if def.CompactorCheckInterval != 50*time.Millisecond {
+		t.Fatalf("default CompactorCheckInterval = %v, want 50ms", def.CompactorCheckInterval)
+	}
+	if def.CompactorInitialDelay != 0 {
+		t.Fatalf("default CompactorInitialDelay = %v, want 0 (legacy random stagger)",
+			def.CompactorInitialDelay)
+	}
+
+	configured := def.
+		WithCompactorCheckInterval(2 * time.Second).
+		WithCompactorInitialDelay(3 * time.Second)
+	if configured.CompactorCheckInterval != 2*time.Second {
+		t.Fatalf("configured CompactorCheckInterval = %v, want 2s",
+			configured.CompactorCheckInterval)
+	}
+	if configured.CompactorInitialDelay != 3*time.Second {
+		t.Fatalf("configured CompactorInitialDelay = %v, want 3s",
+			configured.CompactorInitialDelay)
+	}
+	if got := configured.compactorCheckInterval(); got != 2*time.Second {
+		t.Fatalf("compactorCheckInterval() = %v, want 2s", got)
+	}
+	if got := configured.compactorInitialDelay(); got != 3*time.Second {
+		t.Fatalf("compactorInitialDelay() = %v, want 3s", got)
+	}
+
+	if got := (Options{}).compactorCheckInterval(); got != 50*time.Millisecond {
+		t.Fatalf("zero compactorCheckInterval() = %v, want the 50ms default", got)
+	}
+	for i := 0; i < 100; i++ {
+		if got := def.compactorInitialDelay(); got < 0 || got >= time.Second {
+			t.Fatalf("default compactorInitialDelay() = %v, want a value in [0, 1s)", got)
+		}
+	}
+
+	for _, tc := range []struct {
+		interval time.Duration
+		want     int
+	}{
+		{interval: 50 * time.Millisecond, want: 200},
+		{interval: 2 * time.Second, want: 5},
+		{interval: 30 * time.Second, want: 1},
+	} {
+		if got := compactorLmaxTicks(tc.interval); got != tc.want {
+			t.Fatalf("compactorLmaxTicks(%v) = %d, want %d", tc.interval, got, tc.want)
+		}
+	}
+
+	invalidInterval := DefaultOptions("")
+	invalidInterval.CompactorCheckInterval = -time.Millisecond
+	if err := checkAndSetOptions(&invalidInterval); err == nil {
+		t.Fatal("checkAndSetOptions accepted a negative CompactorCheckInterval")
+	}
+
+	invalidDelay := DefaultOptions("")
+	invalidDelay.CompactorInitialDelay = -time.Millisecond
+	if err := checkAndSetOptions(&invalidDelay); err == nil {
+		t.Fatal("checkAndSetOptions accepted a negative CompactorInitialDelay")
+	}
+}
+
 // optionsEqual just compares the values of two Options structs
 func optionsEqual(o1, o2 Options) bool {
 	o1v := reflect.ValueOf(&o1).Elem()