Fix memory leak in case cached data forms a reference cycle

sc now requires Go 1.24+ since this is dependent on weak package.
See issue #8.

Author: motoki317

.github/workflows/main.yaml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       matrix:
         go:
-          - "1.22"
+          - "1.24"
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-go@v3
@@ -30,7 +30,7 @@ jobs:
     strategy:
       matrix:
         go:
-          - "1.22"
+          - "1.24"
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-go@v3
@@ -47,7 +47,7 @@ jobs:
     strategy:
       matrix:
         go:
-          - "1.22"
+          - "1.24"
     env:
       GOCACHE: "/tmp/go/cache"
     steps:
@@ -81,7 +81,7 @@ jobs:
     strategy:
       matrix:
         go:
-          - "1.22"
+          - "1.24"
     steps:
       - uses: actions/checkout@v3
         with:

cache_test.go

@@ -1170,6 +1170,28 @@ func TestCleaningCache(t *testing.T) {
 func TestCleaningCacheFinalizer(t *testing.T) {
 	t.Parallel()
 
+	for _, c := range allCaches(10) {
+		c := c
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			replaceFn := func(_ context.Context, _ struct{}) (string, error) { return "value", nil }
+			ca, err := New(replaceFn, time.Hour, time.Hour, append(c.cacheOpts, WithCleanupInterval(time.Second))...)
+			assert.NoError(t, err)
+
+			_, _ = ca.Get(context.Background(), struct{}{})
+			runtime.KeepAlive(ca)
+			runtime.GC() // finalizer is called and cleaner is stopped
+			time.Sleep(1 * time.Second)
+		})
+	}
+}
+
+// TestCleaningCacheFinalizer_ReferenceCycle is like TestCleaningCacheFinalizer, but tests case when cached data contains
+// a reference to *Cache itself.
+func TestCleaningCacheFinalizer_ReferenceCycle(t *testing.T) {
+	t.Parallel()
+
 	for _, c := range allCaches(10) {
 		c := c
 		t.Run(c.name, func(t *testing.T) {
@@ -1187,8 +1209,9 @@ func TestCleaningCacheFinalizer(t *testing.T) {
 			assert.NoError(t, err)
 
 			_, _ = ca.Get(context.Background(), struct{}{})
-			runtime.KeepAlive(c)
+			runtime.KeepAlive(ca)
 			runtime.GC() // finalizer is called and cleaner is stopped
+			time.Sleep(1 * time.Second)
 		})
 	}
 }

cleaner.go

@@ -3,6 +3,7 @@ package sc
 import (
 	"runtime"
 	"time"
+	"weak"
 )
 
 // cleaner is launched as a single goroutine to regularly clean up expired items from the cache.
@@ -11,16 +12,24 @@ import (
 // See https://github.com/patrickmn/go-cache/blob/46f407853014144407b6c2ec7ccc76bf67958d93/cache.go#L1115 for more on this design.
 type cleaner[K comparable, V any] struct {
 	closer chan struct{}
-	c      *cache[K, V]
+	// We use weak pointer here in order to deal with an extremely-unlikely case where cached data itself
+	// somehow has a reference to *Cache itself, forming a reference cycle.
+	// If above is the case, and we're using strong reference here, the cleaner goroutine keeps a reference to this
+	// reference cycle, therefore *Cache and *cache never being evicted, leading to memory leaks.
+	//
+	// This case can be tested in TestCleaningCacheFinalizer, where testers can manually check that stopCleaner function
+	// is called, for example by adding `fmt.Println("cleanup called")` there.
+	c weak.Pointer[cache[K, V]]
 }
 
 func startCleaner[K comparable, V any](c *Cache[K, V], interval time.Duration) {
+	closer := make(chan struct{})
 	cl := &cleaner[K, V]{
-		closer: make(chan struct{}),
-		c:      c.cache,
+		closer: closer,
+		c:      weak.Make(c.cache),
 	}
 	go cl.run(interval)
-	runtime.SetFinalizer(c, stopCleaner(cl))
+	runtime.AddCleanup(c, stopCleaner, closer)
 }
 
 func (cl *cleaner[K, V]) run(interval time.Duration) {
@@ -29,19 +38,17 @@ func (cl *cleaner[K, V]) run(interval time.Duration) {
 	for {
 		select {
 		case <-ticker.C:
-			cl.c.cleanup()
+			c := cl.c.Value()
+			if c == nil {
+				return
+			}
+			c.cleanup()
 		case <-cl.closer:
 			return
 		}
 	}
 }
 
-func (cl *cleaner[K, V]) stop() {
-	cl.closer <- struct{}{}
-}
-
-func stopCleaner[K comparable, V any](cl *cleaner[K, V]) func(*Cache[K, V]) {
-	return func(_ *Cache[K, V]) {
-		cl.stop()
-	}
+func stopCleaner(closer chan<- struct{}) {
+	close(closer)
 }

go.mod

@@ -1,8 +1,10 @@
 module github.com/motoki317/sc
 
-go 1.21
+go 1.24
 
-require github.com/stretchr/testify v1.9.0
+toolchain go1.24.1
+
+require github.com/stretchr/testify v1.10.0
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect

go.sum

@@ -9,8 +9,8 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
-github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=