gopls/internal/lsp/lru: extract LRU logic to a standalone package

Extract a simple LRU package from the parseCache implementation (which
itself was extracted from an initial implementation of the filecache).

In a subsequent CL, this package will be used to reduce I/O in the
filecache package.

For golang/go#57987

Change-Id: I307f397b71654226d4e0e1c532a81cfde49af831
Reviewed-on: https://go-review.googlesource.com/c/tools/+/494099
Reviewed-by: Alan Donovan <[email protected]>
Run-TryBot: Robert Findley <[email protected]>
gopls-CI: kokoro <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>

Author: findleyr

gopls/internal/lsp/lru/lru.go

@@ -0,0 +1,153 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// The lru package implements a fixed-size in-memory LRU cache.
+package lru
+
+import (
+	"container/heap"
+	"fmt"
+	"sync"
+)
+
+type any = interface{} // TODO: remove once gopls only builds at go1.18+
+
+// A Cache is a fixed-size in-memory LRU cache.
+type Cache struct {
+	capacity int
+
+	mu    sync.Mutex
+	used  int            // used capacity, in user-specified units
+	m     map[any]*entry // k/v lookup
+	lru   queue          // min-atime priority queue of *entry
+	clock int64          // clock time, incremented whenever the cache is updated
+}
+
+type entry struct {
+	key   any
+	value any
+	size  int   // caller-specified size
+	atime int64 // last access / set time
+	index int   // index of entry in the heap slice
+}
+
+// New creates a new Cache with the given capacity, which must be positive.
+//
+// The cache capacity uses arbitrary units, which are specified during the Set
+// operation.
+func New(capacity int) *Cache {
+	if capacity == 0 {
+		panic("zero capacity")
+	}
+
+	return &Cache{
+		capacity: capacity,
+		m:        make(map[any]*entry),
+	}
+}
+
+// Get retrieves the value for the specified key, or nil if the key is not
+// found.
+//
+// If the key is found, its access time is updated.
+func (c *Cache) Get(key any) any {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.clock++ // every access updates the clock
+
+	if e, ok := c.m[key]; ok { // cache hit
+		e.atime = c.clock
+		heap.Fix(&c.lru, e.index)
+		return e.value
+	}
+
+	return nil
+}
+
+// Set stores a value for the specified key, using its given size to update the
+// current cache size, evicting old entries as necessary to fit in the cache
+// capacity.
+//
+// Size must be a non-negative value. If size is larger than the cache
+// capacity, the value is not stored and the cache is not modified.
+func (c *Cache) Set(key, value any, size int) {
+	if size < 0 {
+		panic(fmt.Sprintf("size must be non-negative, got %d", size))
+	}
+	if size > c.capacity {
+		return // uncacheable
+	}
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.clock++
+
+	// Remove the existing cache entry for key, if it exists.
+	e, ok := c.m[key]
+	if ok {
+		c.used -= e.size
+		heap.Remove(&c.lru, e.index)
+		delete(c.m, key)
+	}
+
+	// Evict entries until the new value will fit.
+	newUsed := c.used + size
+	if newUsed < 0 {
+		return // integer overflow; return silently
+	}
+	c.used = newUsed
+	for c.used > c.capacity {
+		// evict oldest entry
+		e = heap.Pop(&c.lru).(*entry)
+		c.used -= e.size
+		delete(c.m, e.key)
+	}
+
+	// Store the new value.
+	// Opt: e is evicted, so it can be reused to reduce allocation.
+	if e == nil {
+		e = new(entry)
+	}
+	e.key = key
+	e.value = value
+	e.size = size
+	e.atime = c.clock
+	c.m[e.key] = e
+	heap.Push(&c.lru, e)
+
+	if len(c.m) != len(c.lru) {
+		panic("map and LRU are inconsistent")
+	}
+}
+
+// -- priority queue boilerplate --
+
+// queue is a min-atime priority queue of cache entries.
+type queue []*entry
+
+func (q queue) Len() int { return len(q) }
+
+func (q queue) Less(i, j int) bool { return q[i].atime < q[j].atime }
+
+func (q queue) Swap(i, j int) {
+	q[i], q[j] = q[j], q[i]
+	q[i].index = i
+	q[j].index = j
+}
+
+func (q *queue) Push(x any) {
+	e := x.(*entry)
+	e.index = len(*q)
+	*q = append(*q, e)
+}
+
+func (q *queue) Pop() any {
+	last := len(*q) - 1
+	e := (*q)[last]
+	(*q)[last] = nil // aid GC
+	*q = (*q)[:last]
+	return e
+}

gopls/internal/lsp/lru/lru_fuzz_test.go

@@ -0,0 +1,41 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+//go:build go1.18
+// +build go1.18
+
+package lru_test
+
+import (
+	"testing"
+
+	"golang.org/x/tools/gopls/internal/lsp/lru"
+)
+
+// Simple fuzzing test for consistency.
+func FuzzCache(f *testing.F) {
+	type op struct {
+		set        bool
+		key, value byte
+	}
+	f.Fuzz(func(t *testing.T, data []byte) {
+		var ops []op
+		for len(data) >= 3 {
+			ops = append(ops, op{data[0]%2 == 0, data[1], data[2]})
+			data = data[3:]
+		}
+		cache := lru.New(100)
+		var reference [256]byte
+		for _, op := range ops {
+			if op.set {
+				reference[op.key] = op.value
+				cache.Set(op.key, op.value, 1)
+			} else {
+				if v := cache.Get(op.key); v != nil && v != reference[op.key] {
+					t.Fatalf("cache.Get(%d) = %d, want %d", op.key, v, reference[op.key])
+				}
+			}
+		}
+	})
+}

gopls/internal/lsp/lru/lru_test.go

@@ -0,0 +1,156 @@
+// Copyright 2023 The Go 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 lru_test
+
+import (
+	"bytes"
+	cryptorand "crypto/rand"
+	"fmt"
+	"log"
+	mathrand "math/rand"
+	"strings"
+	"testing"
+
+	"golang.org/x/sync/errgroup"
+	"golang.org/x/tools/gopls/internal/lsp/lru"
+)
+
+type any = interface{} // TODO: remove once gopls only builds at go1.18+
+
+func TestCache(t *testing.T) {
+	type get struct {
+		key  string
+		want any
+	}
+	type set struct {
+		key, value string
+	}
+
+	tests := []struct {
+		label string
+		steps []any
+	}{
+		{"empty cache", []any{
+			get{"a", nil},
+			get{"b", nil},
+		}},
+		{"zero-length string", []any{
+			set{"a", ""},
+			get{"a", ""},
+		}},
+		{"under capacity", []any{
+			set{"a", "123"},
+			set{"b", "456"},
+			get{"a", "123"},
+			get{"b", "456"},
+		}},
+		{"over capacity", []any{
+			set{"a", "123"},
+			set{"b", "456"},
+			set{"c", "78901"},
+			get{"a", nil},
+			get{"b", "456"},
+			get{"c", "78901"},
+		}},
+		{"access ordering", []any{
+			set{"a", "123"},
+			set{"b", "456"},
+			get{"a", "123"},
+			set{"c", "78901"},
+			get{"a", "123"},
+			get{"b", nil},
+			get{"c", "78901"},
+		}},
+	}
+
+	for _, test := range tests {
+		t.Run(test.label, func(t *testing.T) {
+			c := lru.New(10)
+			for i, step := range test.steps {
+				switch step := step.(type) {
+				case get:
+					if got := c.Get(step.key); got != step.want {
+						t.Errorf("#%d: c.Get(%q) = %q, want %q", i, step.key, got, step.want)
+					}
+				case set:
+					c.Set(step.key, step.value, len(step.value))
+				}
+			}
+		})
+	}
+}
+
+// TestConcurrency exercises concurrent access to the same entry.
+//
+// It is a copy of TestConcurrency from the filecache package.
+func TestConcurrency(t *testing.T) {
+	key := uniqueKey()
+	const N = 100 // concurrency level
+
+	// Construct N distinct values, each larger
+	// than a typical 4KB OS file buffer page.
+	var values [N][8192]byte
+	for i := range values {
+		if _, err := mathrand.Read(values[i][:]); err != nil {
+			t.Fatalf("rand: %v", err)
+		}
+	}
+
+	cache := lru.New(100 * 1e6) // 100MB cache
+
+	// get calls Get and verifies that the cache entry
+	// matches one of the values passed to Set.
+	get := func(mustBeFound bool) error {
+		got := cache.Get(key)
+		if got == nil {
+			if !mustBeFound {
+				return nil
+			}
+			return fmt.Errorf("Get did not return a value")
+		}
+		gotBytes := got.([]byte)
+		for _, want := range values {
+			if bytes.Equal(want[:], gotBytes) {
+				return nil // a match
+			}
+		}
+		return fmt.Errorf("Get returned a value that was never Set")
+	}
+
+	// Perform N concurrent calls to Set and Get.
+	// All sets must succeed.
+	// All gets must return nothing, or one of the Set values;
+	// there is no third possibility.
+	var group errgroup.Group
+	for i := range values {
+		i := i
+		v := values[i][:]
+		group.Go(func() error {
+			cache.Set(key, v, len(v))
+			return nil
+		})
+		group.Go(func() error { return get(false) })
+	}
+	if err := group.Wait(); err != nil {
+		if strings.Contains(err.Error(), "operation not supported") ||
+			strings.Contains(err.Error(), "not implemented") {
+			t.Skipf("skipping: %v", err)
+		}
+		t.Fatal(err)
+	}
+
+	// A final Get must report one of the values that was Set.
+	if err := get(true); err != nil {
+		t.Fatalf("final Get failed: %v", err)
+	}
+}
+
+// uniqueKey returns a key that has never been used before.
+func uniqueKey() (key [32]byte) {
+	if _, err := cryptorand.Read(key[:]); err != nil {
+		log.Fatalf("rand: %v", err)
+	}
+	return
+}