base: move cache.Level to base

We also rework the implementation so it's less confusing.

Author: RaduBerinde

db_test.go

@@ -858,7 +858,7 @@ func TestMemTableReservation(t *testing.T) {
 		t.Fatalf("expected 2 refs, but found %d", refs)
 	}
 	// Verify the memtable reservation has caused our test block to be evicted.
-	if cv := tmpHandle.Peek(base.DiskFileNum(0), 0, cache.MakeLevel(0), cache.CategoryBackground); cv != nil {
+	if cv := tmpHandle.Peek(base.DiskFileNum(0), 0, base.MakeLevel(0), cache.CategoryBackground); cv != nil {
 		t.Fatalf("expected failure, but found success: %#v", cv)
 	}
 

file_cache.go

@@ -591,7 +591,7 @@ func (h *fileCacheHandle) newIters(
 	internalOpts.readEnv.IsSharedIngested = env.IsSharedIngested
 	internalOpts.readEnv.InternalBounds = env.InternalBounds
 	if opts != nil && opts.layer.IsSet() && !opts.layer.IsFlushableIngests() {
-		internalOpts.readEnv.Block.Level = cache.MakeLevel(opts.layer.Level())
+		internalOpts.readEnv.Block.Level = base.MakeLevel(opts.layer.Level())
 	}
 
 	var iters iterSet

internal/base/level.go

@@ -0,0 +1,44 @@
+// Copyright 2025 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+package base
+
+import (
+	"fmt"
+
+	"github.com/cockroachdb/errors"
+	"github.com/cockroachdb/pebble/internal/invariants"
+)
+
+// Level identifies an LSM level. The zero value indicates that the level is
+// uninitialized or unknown.
+type Level struct {
+	// v contains the level in the lowest 7 bits. The highest bit is set iff the
+	// value is valid.
+	v uint8
+}
+
+const validBit = 1 << 7
+
+func (l Level) Get() (level int, ok bool) {
+	return int(l.v &^ validBit), l.Valid()
+}
+
+func (l Level) Valid() bool {
+	return l.v&validBit != 0
+}
+
+func (l Level) String() string {
+	if level, ok := l.Get(); ok {
+		return fmt.Sprintf("L%d", level)
+	}
+	return "n/a"
+}
+
+func MakeLevel(l int) Level {
+	if invariants.Enabled && l < 0 || l >= validBit {
+		panic(errors.AssertionFailedf("invalid level: %d", l))
+	}
+	return Level{uint8(l) | validBit}
+}

internal/cache/cache.go

@@ -253,7 +253,7 @@ func (c *Handle) Cache() *Cache {
 // Peek supports the special CategoryHidden category, in which case the hit or
 // miss is not recorded in metrics.
 func (c *Handle) Peek(
-	fileNum base.DiskFileNum, offset uint64, level Level, category Category,
+	fileNum base.DiskFileNum, offset uint64, level base.Level, category Category,
 ) *Value {
 	k := makeKey(c.id, fileNum, offset)
 	return c.cache.getShard(k).get(k, level, category, true /* peekOnly */)
@@ -265,7 +265,7 @@ const CategoryHidden Category = -1
 // Get retrieves the cache value for the specified file and offset, returning
 // nil if no value is present.
 func (c *Handle) Get(
-	fileNum base.DiskFileNum, offset uint64, level Level, category Category,
+	fileNum base.DiskFileNum, offset uint64, level base.Level, category Category,
 ) *Value {
 	k := makeKey(c.id, fileNum, offset)
 	return c.cache.getShard(k).get(k, level, category, false /* peekOnly */)
@@ -295,7 +295,7 @@ func (c *Handle) Get(
 // While waiting, someone else may successfully read the value, which results
 // in a valid Handle being returned. This is a case where cacheHit=false.
 func (c *Handle) GetWithReadHandle(
-	ctx context.Context, fileNum base.DiskFileNum, offset uint64, level Level, category Category,
+	ctx context.Context, fileNum base.DiskFileNum, offset uint64, level base.Level, category Category,
 ) (
 	cv *Value,
 	rh ReadHandle,

internal/cache/cache_test.go

@@ -41,7 +41,7 @@ func TestCache(t *testing.T) {
 		wantHit := fields[1][0] == 'h'
 
 		var hit bool
-		cv := h.Get(base.DiskFileNum(key), 0, MakeLevel(0), CategorySSTableData)
+		cv := h.Get(base.DiskFileNum(key), 0, base.MakeLevel(0), CategorySSTableData)
 		if cv == nil {
 			cv = Alloc(1)
 			cv.RawBuffer()[0] = fields[0][0]
@@ -81,14 +81,14 @@ func TestCachePeek(t *testing.T) {
 		setTestValue(h, 0, uint64(i), "a", 1)
 	}
 	for i := range size / 2 {
-		v := h.Get(base.DiskFileNum(0), uint64(i), MakeLevel(0), CategoryBackground)
+		v := h.Get(base.DiskFileNum(0), uint64(i), base.MakeLevel(0), CategoryBackground)
 		if v == nil {
 			t.Fatalf("expected to find block %d", i)
 		}
 		v.Release()
 	}
 	for i := size / 2; i < size; i++ {
-		v := h.Peek(base.DiskFileNum(0), uint64(i), MakeLevel(0), CategoryBackground)
+		v := h.Peek(base.DiskFileNum(0), uint64(i), base.MakeLevel(0), CategoryBackground)
 		if v == nil {
 			t.Fatalf("expected to find block %d", i)
 		}
@@ -100,7 +100,7 @@ func TestCachePeek(t *testing.T) {
 	}
 	// Verify that the Gets still find their values, despite the Peeks.
 	for i := range size / 2 {
-		v := h.Get(base.DiskFileNum(0), uint64(i), MakeLevel(0), CategoryBackground)
+		v := h.Get(base.DiskFileNum(0), uint64(i), base.MakeLevel(0), CategoryBackground)
 		if v == nil {
 			t.Fatalf("expected to find block %d", i)
 		}
@@ -124,12 +124,12 @@ func TestCacheDelete(t *testing.T) {
 	if expected, size := int64(10), cache.Size(); expected != size {
 		t.Fatalf("expected cache size %d, but found %d", expected, size)
 	}
-	if v := h.Get(base.DiskFileNum(0), 0, MakeLevel(0), CategorySSTableData); v == nil {
+	if v := h.Get(base.DiskFileNum(0), 0, base.MakeLevel(0), CategorySSTableData); v == nil {
 		t.Fatalf("expected to find block 0/0")
 	} else {
 		v.Release()
 	}
-	if v := h.Get(base.DiskFileNum(1), 0, MakeLevel(0), CategorySSTableData); v != nil {
+	if v := h.Get(base.DiskFileNum(1), 0, base.MakeLevel(0), CategorySSTableData); v != nil {
 		t.Fatalf("expected to not find block 1/0")
 	}
 	// Deleting a non-existing block does nothing.
@@ -196,11 +196,11 @@ func TestMultipleDBs(t *testing.T) {
 	if expected, size := int64(5), cache.Size(); expected != size {
 		t.Fatalf("expected cache size %d, but found %d", expected, size)
 	}
-	v := h1.Get(base.DiskFileNum(0), 0, MakeLevel(0), CategorySSTableData)
+	v := h1.Get(base.DiskFileNum(0), 0, base.MakeLevel(0), CategorySSTableData)
 	if v != nil {
 		t.Fatalf("expected not present, but found %#v", v)
 	}
-	v = h2.Get(base.DiskFileNum(0), 0, MakeLevel(0), CategorySSTableData)
+	v = h2.Get(base.DiskFileNum(0), 0, base.MakeLevel(0), CategorySSTableData)
 	if v := v.RawBuffer(); string(v) != "bbbbb" {
 		t.Fatalf("expected bbbbb, but found %s", v)
 	}
@@ -308,7 +308,10 @@ func BenchmarkCacheGet(b *testing.B) {
 		for pb.Next() {
 			randVal := pcg.Uint64()
 			offset := randVal % size
-			level := Level{levelPlusOne: int8((randVal >> 32) % NumLevels)}
+			var level base.Level
+			if l := int((randVal >> 32) % NumLevels); l > 0 {
+				level = base.MakeLevel(l - 1)
+			}
 			category := Category((randVal >> 48) % uint64(NumCategories))
 			v := h.Get(base.DiskFileNum(0), offset, level, category)
 			if v == nil {

internal/cache/clockpro.go

@@ -138,7 +138,7 @@ func (c *shard) init(maxSize int64) {
 //
 // If peekOnly is true, the state of the cache is not modified to reflect the
 // access.
-func (c *shard) get(k key, level Level, category Category, peekOnly bool) *Value {
+func (c *shard) get(k key, level base.Level, category Category, peekOnly bool) *Value {
 	c.mu.RLock()
 	if e, _ := c.blocks.Get(k); e != nil {
 		if value := e.acquireValue(); value != nil {
@@ -148,14 +148,14 @@ func (c *shard) get(k key, level Level, category Category, peekOnly bool) *Value
 			}
 			c.mu.RUnlock()
 			if category != CategoryHidden {
-				c.counters[level.index()][category].hits.Add(1)
+				c.counters[levelIndex(level)][category].hits.Add(1)
 			}
 			return value
 		}
 	}
 	c.mu.RUnlock()
 	if category != CategoryHidden {
-		c.counters[level.index()][category].misses.Add(1)
+		c.counters[levelIndex(level)][category].misses.Add(1)
 	}
 	return nil
 }
@@ -165,7 +165,7 @@ func (c *shard) get(k key, level Level, category Category, peekOnly bool) *Value
 // is not in the cache (nil Value), a non-nil readEntry is returned (in which
 // case the caller is responsible to dereference the entry, via one of
 // unrefAndTryRemoveFromMap(), setReadValue(), setReadError()).
-func (c *shard) getWithReadEntry(k key, level Level, category Category) (*Value, *readEntry) {
+func (c *shard) getWithReadEntry(k key, level base.Level, category Category) (*Value, *readEntry) {
 	c.mu.RLock()
 	if e, _ := c.blocks.Get(k); e != nil {
 		if value := e.acquireValue(); value != nil {
@@ -174,13 +174,13 @@ func (c *shard) getWithReadEntry(k key, level Level, category Category) (*Value,
 				e.referenced.Store(true)
 			}
 			c.mu.RUnlock()
-			c.counters[level.index()][category].hits.Add(1)
+			c.counters[levelIndex(level)][category].hits.Add(1)
 			return value, nil
 		}
 	}
 	re := c.readShard.acquireReadEntry(k)
 	c.mu.RUnlock()
-	c.counters[level.index()][category].misses.Add(1)
+	c.counters[levelIndex(level)][category].misses.Add(1)
 	return nil, re
 }
 

internal/cache/metrics.go

@@ -9,50 +9,33 @@ import (
 	"iter"
 
 	"github.com/cockroachdb/crlib/crtime"
-	"github.com/cockroachdb/errors"
-	"github.com/cockroachdb/pebble/internal/invariants"
+	"github.com/cockroachdb/pebble/internal/base"
 )
 
-// Level is the LSM level associated with an accessed block. Used to maintain
-// granular cache hit/miss statistics.
-//
-// The zero value indicates that there is no level (e.g. flushable ingests) or
-// it is unknown.
-type Level struct {
-	levelPlusOne int8
-}
+const NumLevels = 1 /* unknown level */ + 7
 
-func (l Level) String() string {
-	if l.levelPlusOne <= 0 {
-		return "n/a"
+// Levels is an iter.Seq[base.Level] that produces all the levels in the
+// HitsAndMisses array.
+func Levels(yield func(l base.Level) bool) {
+	if !yield(base.Level{}) {
+		return
 	}
-	return fmt.Sprintf("L%d", l.levelPlusOne-1)
-}
-
-// index returns a value between [0, NumLevels).
-func (l Level) index() int8 {
-	return l.levelPlusOne
-}
-
-func MakeLevel(l int) Level {
-	if invariants.Enabled && (l < 0 || l >= NumLevels-1) {
-		panic(errors.AssertionFailedf("invalid level: %d", l))
+	for i := range NumLevels - 1 {
+		if !yield(base.MakeLevel(i)) {
+			return
+		}
 	}
-	return Level{levelPlusOne: int8(l + 1)}
 }
 
-const NumLevels = 1 /* unknown level */ + 7
-
-// Levels is an iter.Seq[Level].
-func Levels(yield func(l Level) bool) {
-	for i := range NumLevels {
-		if !yield(Level{levelPlusOne: int8(i)}) {
-			return
-		}
+// levelIndex returns the index of level in the HitsAndMisses array.
+func levelIndex(level base.Level) int {
+	if l, ok := level.Get(); ok {
+		return l + 1
 	}
+	return 0
 }
 
-var _ iter.Seq[Level] = Levels
+var _ iter.Seq[base.Level] = Levels
 
 // Category is used to maintain granular cache hit/miss statistics.
 type Category int8
@@ -117,17 +100,17 @@ type HitsAndMisses [NumLevels][NumCategories]struct {
 	Misses int64
 }
 
-func (hm *HitsAndMisses) Get(level Level, category Category) (hits, misses int64) {
-	v := hm[level.index()][category]
+func (hm *HitsAndMisses) Get(level base.Level, category Category) (hits, misses int64) {
+	v := hm[levelIndex(level)][category]
 	return v.Hits, v.Misses
 }
 
-func (hm *HitsAndMisses) Hits(level Level, category Category) int64 {
-	return hm[level.index()][category].Hits
+func (hm *HitsAndMisses) Hits(level base.Level, category Category) int64 {
+	return hm[levelIndex(level)][category].Hits
 }
 
-func (hm *HitsAndMisses) Misses(level Level, category Category) int64 {
-	return hm[level.index()][category].Misses
+func (hm *HitsAndMisses) Misses(level base.Level, category Category) int64 {
+	return hm[levelIndex(level)][category].Misses
 }
 
 // Aggregate returns the total hits and misses across all categories and levels.
@@ -143,8 +126,8 @@ func (hm *HitsAndMisses) Aggregate() (hits, misses int64) {
 
 // AggregateLevel returns the total hits and misses for a specific level (across
 // all categories).
-func (hm *HitsAndMisses) AggregateLevel(level Level) (hits, misses int64) {
-	for _, v := range hm[level.index()] {
+func (hm *HitsAndMisses) AggregateLevel(level base.Level) (hits, misses int64) {
+	for _, v := range hm[levelIndex(level)] {
 		hits += v.Hits
 		misses += v.Misses
 	}

internal/cache/read_shard_test.go

@@ -50,7 +50,7 @@ func newTestReader(
 }
 
 func (r *testReader) getAsync(shard *shard) *string {
-	v, re := shard.getWithReadEntry(r.key, MakeLevel(0), CategorySSTableData)
+	v, re := shard.getWithReadEntry(r.key, base.MakeLevel(0), CategorySSTableData)
 	if v != nil {
 		str := string(v.RawBuffer())
 		v.Release()
@@ -285,7 +285,7 @@ func TestReadShardConcurrent(t *testing.T) {
 	for _, r := range differentReaders {
 		for j := 0; j < r.numReaders; j++ {
 			go func(r *testSyncReaders, index int) {
-				v, rh, _, _, _, err := r.handle.GetWithReadHandle(context.Background(), r.fileNum, r.offset, MakeLevel(0), CategorySSTableData)
+				v, rh, _, _, _, err := r.handle.GetWithReadHandle(context.Background(), r.fileNum, r.offset, base.MakeLevel(0), CategorySSTableData)
 				require.NoError(t, err)
 				if v != nil {
 					require.Equal(t, r.val, v.RawBuffer())

sstable/block/block.go

@@ -276,7 +276,7 @@ type ReadEnv struct {
 	// Level is the LSM level associated with the operation, when the operation
 	// applies to a (possibly virtual) sstable. It is used when interacting with
 	// the block cache.
-	Level cache.Level
+	Level base.Level
 
 	// ReportCorruptionFn is called with ReportCorruptionArg and the error
 	// whenever an SSTable corruption is detected. The argument is used to avoid
@@ -566,7 +566,7 @@ func (r *Reader) Readable() objstorage.Readable {
 //
 // Users should prefer using Read, which handles reading from object storage on
 // a cache miss.
-func (r *Reader) GetFromCache(bh Handle, level cache.Level) *cache.Value {
+func (r *Reader) GetFromCache(bh Handle, level base.Level) *cache.Value {
 	return r.opts.CacheOpts.CacheHandle.Peek(r.opts.CacheOpts.FileNum, bh.Offset, level, cache.CategoryBackground)
 }
 

sstable/colblk/index_block_test.go

@@ -132,7 +132,7 @@ func TestIndexIterInitHandle(t *testing.T) {
 	}
 
 	getBlockAndIterate := func(it *IndexIter) {
-		cv := ch.Get(base.DiskFileNum(1), 0, cache.MakeLevel(0), cache.CategorySSTableData)
+		cv := ch.Get(base.DiskFileNum(1), 0, base.MakeLevel(0), cache.CategorySSTableData)
 		require.NotNil(t, cv)
 		require.NoError(t, it.InitHandle(testkeys.Comparer, block.CacheBufferHandle(cv), blockiter.NoTransforms))
 		defer it.Close()