Cleanups, Weak Pointers and Interning

package main

import (
	"fmt"
	"runtime"
	"sync/atomic"
	"time"
)

// Scanner and Session point at each other, as a device and its owner often do.
type Scanner struct {
	fd      int
	session *Session
}

type Session struct {
	scanner *Scanner
}

var finalized, cleaned atomic.Int32

func newPair(fd int) *Scanner {
	s := &Scanner{fd: fd}
	s.session = &Session{scanner: s}
	return s
}

func makeWithFinalizer() {
	s := newPair(1)
	runtime.SetFinalizer(s, func(*Scanner) { finalized.Add(1) })
}

func makeWithCleanup() {
	s := newPair(2)
	runtime.AddCleanup(s, func(int) { cleaned.Add(1) }, s.fd)
}

func main() {
	makeWithFinalizer()
	makeWithCleanup()

	for range 10 {
		runtime.GC()
		time.Sleep(10 * time.Millisecond)
	}
	fmt.Println("finalizers run for the cyclic pair:", finalized.Load())
	fmt.Println("cleanups run for the cyclic pair:  ", cleaned.Load())
}

finalizers run for the cyclic pair: 0
cleanups run for the cyclic pair:   1

package main

import (
	"fmt"
	"runtime"
	"sync/atomic"
	"time"
)

type node struct{ next *node }

var finalized atomic.Int32

func build(n int) {
	var head *node
	for range n {
		head = &node{next: head}
		runtime.SetFinalizer(head, func(*node) { finalized.Add(1) })
	}
}

func main() {
	build(5)
	for cycle := 1; cycle <= 8; cycle++ {
		runtime.GC()
		time.Sleep(20 * time.Millisecond)
		fmt.Printf("after GC %d: %d of 5 finalizers have run\n", cycle, finalized.Load())
	}
}

after GC 1: 1 of 5 finalizers have run
after GC 2: 2 of 5 finalizers have run
after GC 3: 3 of 5 finalizers have run
after GC 4: 4 of 5 finalizers have run
after GC 5: 5 of 5 finalizers have run
after GC 6: 5 of 5 finalizers have run
after GC 7: 5 of 5 finalizers have run
after GC 8: 5 of 5 finalizers have run

package main

import "runtime"

type Scanner struct{ fd int }

func main() {
	s := &Scanner{fd: 3}
	// The argument equals the pointer: the cleanup could never run.
	runtime.AddCleanup(s, func(*Scanner) {}, s)
}

panic: runtime.AddCleanup: ptr is equal to arg, cleanup will never run

goroutine 1 [running]:
main.main()
	.../main.go:10 +0x50

package main

import "runtime"

type Scanner struct{ fd int }

func main() {
	s := &Scanner{fd: 3}
	// The closure refers to s directly: the runtime detects this simple case.
	runtime.AddCleanup(s, func(int) { println("closing", s.fd) }, s.fd)
}

panic: runtime.AddCleanup: cleanup function closes over ptr, cleanup will never run

goroutine 1 [running]:
main.main()
	.../main.go:10 +0x90

package main

import (
	"fmt"
	"runtime"
	"time"
)

type Scanner struct{ fd int }

func (s *Scanner) release() { fmt.Println("closing", s.fd) }

// job refers back to the scanner, e.g. a queue entry that records its owner.
type job struct{ owner *Scanner }

func openScanner(ran *bool) {
	s := &Scanner{fd: 3}
	// Wrong: the argument reaches s, so s stays reachable from the
	// runtime's own cleanup record. The runtime cannot spot this
	// indirect path, so there is no panic: the cleanup silently never runs.
	runtime.AddCleanup(s, func(j *job) {
		*ran = true
		j.owner.release()
	}, &job{owner: s})
}

func main() {
	ran := false
	openScanner(&ran)

	for range 5 {
		runtime.GC()
		time.Sleep(20 * time.Millisecond)
	}
	fmt.Println("cleanup ran:", ran)
}

cleanup ran: false

Value of type main.Scanner at 0x41c49bb96020
  is reachable from cleanup or cleanup argument

Has cleanup at 0x10db27f88
  main.openScanner.func1()
      .../main.go:21 +0x0
created at:
  main.openScanner()
      .../main.go:25 +0xd0

fatal error: detected possible issues with cleanups and/or finalizers

package main

import (
	"fmt"
	"runtime"
	"sync"
	"time"
)

// Scanner has an explicit Close and a cleanup as a safety net for callers
// that forget to call it.
type Scanner struct {
	fd      int
	cleanup runtime.Cleanup
	once    sync.Once
}

func openScanner(fd int) *Scanner {
	s := &Scanner{fd: fd}
	s.cleanup = runtime.AddCleanup(s, func(fd int) {
		fmt.Println("cleanup: forgotten Close, closing device", fd)
	}, fd)
	return s
}

// Close releases the device deterministically and cancels the cleanup.
func (s *Scanner) Close() {
	s.once.Do(func() {
		s.cleanup.Stop()
		fmt.Println("Close: closing device", s.fd)
	})
}

func main() {
	openScanner(1).Close() // explicit Close: the cleanup is stopped
	openScanner(2)         // forgotten: the cleanup is the safety net

	for range 5 {
		runtime.GC()
		time.Sleep(20 * time.Millisecond)
	}
}

Close: closing device 1
cleanup: forgotten Close, closing device 2

package main

import (
	"fmt"
	"runtime"
	"weak"
)

type Scanner struct {
	fd   int
	name string
}

func main() {
	var w weak.Pointer[Scanner]
	resurrected := make(chan *Scanner, 1)

	func() {
		s := &Scanner{fd: 3, name: "desk"}
		w = weak.Make(s)
		// The finalizer resurrects the object by handing it to another goroutine.
		runtime.SetFinalizer(s, func(s *Scanner) { resurrected <- s })
	}()

	runtime.GC()
	// The weak pointer is already cleared although the object still exists:
	// it is waiting in the finalizer queue and then in the channel.
	fmt.Println("weak pointer cleared:", w.Value() == nil)
	s := <-resurrected
	fmt.Println("object still usable, fd:", s.fd)
}

weak pointer cleared: true
object still usable, fd: 3

package main

import (
	"fmt"
	"runtime"
	"sync"
	"time"
	"weak"
)

// Cache memoizes values by key. It holds them only weakly: a value stays in
// the cache for as long as some caller still uses it, and no longer.
type Cache[K comparable, V any] struct {
	mu    sync.Mutex
	items map[K]weak.Pointer[V]
	load  func(K) *V
}

// NewCache returns a cache that calls load on a miss.
func NewCache[K comparable, V any](load func(K) *V) *Cache[K, V] {
	return &Cache[K, V]{items: make(map[K]weak.Pointer[V]), load: load}
}

// Get returns the cached value for key, loading it if needed.
func (c *Cache[K, V]) Get(key K) *V {
	c.mu.Lock()
	defer c.mu.Unlock()

	if wp, ok := c.items[key]; ok {
		if v := wp.Value(); v != nil {
			return v
		}
	}
	v := c.load(key)
	wp := weak.Make(v)
	c.items[key] = wp
	// The cleanup receives only the key. It captures c and wp, neither of
	// which keeps v reachable (wp is weak).
	runtime.AddCleanup(v, func(key K) {
		c.mu.Lock()
		defer c.mu.Unlock()
		// Delete only our own entry: a newer value may have replaced it.
		if c.items[key] == wp {
			delete(c.items, key)
		}
	}, key)
	return v
}

// Len reports how many entries (live or not yet cleaned up) the map holds.
func (c *Cache[K, V]) Len() int {
	c.mu.Lock()
	defer c.mu.Unlock()
	return len(c.items)
}

// Cover is a large cover image that can be reloaded on demand.
type Cover struct {
	ISBN string
	PNG  []byte
}

func heapMiB() uint64 {
	var m runtime.MemStats
	runtime.ReadMemStats(&m)
	return m.HeapAlloc >> 20
}

func main() {
	loads := 0
	covers := NewCache(func(isbn string) *Cover {
		loads++
		return &Cover{ISBN: isbn, PNG: make([]byte, 4<<20)}
	})

	keep := covers.Get("9780134190440") // a caller that keeps using it
	covers.Get("9781492077213")         // used once and dropped
	covers.Get("9781784395438")         // used once and dropped
	fmt.Printf("loaded %d covers, entries: %d, heap: %d MiB\n", loads, covers.Len(), heapMiB())

	// Cleanups run asynchronously: collect and poll until they have run.
	for range 50 {
		runtime.GC()
		if covers.Len() == 1 {
			break
		}
		time.Sleep(10 * time.Millisecond)
	}
	fmt.Printf("after GC, entries: %d, heap: %d MiB\n", covers.Len(), heapMiB())

	again := covers.Get("9780134190440") // still cached: same pointer
	fmt.Println("same cover returned:", again == keep, "loads:", loads)
	covers.Get("9781492077213") // was reclaimed, so it is loaded again
	fmt.Println("loads after re-requesting a dropped cover:", loads)
	runtime.KeepAlive(keep)
}

loaded 3 covers, entries: 3, heap: 12 MiB
after GC, entries: 1, heap: 4 MiB
same cover returned: true loads: 3
loads after re-requesting a dropped cover: 4

package main

import (
	"fmt"
	"runtime"
	"strconv"
	"unique"
)

// Book keeps the publisher either as a plain string or as a handle.
type Book struct {
	Title     string
	Publisher string
}

type InternedBook struct {
	Title     string
	Publisher unique.Handle[string]
}

var publishers = []string{
	"O'Reilly Media", "Packt Publishing", "Addison-Wesley",
	"Manning Publications", "No Starch Press",
}

func heapKiB() uint64 {
	runtime.GC()
	var m runtime.MemStats
	runtime.ReadMemStats(&m)
	return m.HeapAlloc >> 10
}

func main() {
	const n = 200_000
	base := heapKiB()

	// Each record parsed from a feed owns a fresh copy of the publisher name.
	plain := make([]Book, n)
	for i := range plain {
		plain[i] = Book{
			Title:     "Book " + strconv.Itoa(i),
			Publisher: string([]byte(publishers[i%len(publishers)])),
		}
	}
	withPlain := heapKiB()
	runtime.KeepAlive(plain)
	plain = nil

	interned := make([]InternedBook, n)
	for i := range interned {
		interned[i] = InternedBook{
			Title:     "Book " + strconv.Itoa(i),
			Publisher: unique.Make(string([]byte(publishers[i%len(publishers)]))),
		}
	}
	withInterned := heapKiB()
	runtime.KeepAlive(interned)

	fmt.Printf("plain strings:    %d KiB\n", withPlain-base)
	fmt.Printf("unique handles:   %d KiB\n", withInterned-base)
	fmt.Println("same publisher:", interned[0].Publisher == interned[5].Publisher)
}

plain strings:    12839 KiB
unique handles:   7835 KiB
same publisher: true

package uqbench

import (
	"strings"
	"testing"
	"unique"
)

var (
	// Two equal strings long enough that comparing them takes real work.
	nameA = strings.Repeat("Addison-Wesley Professional ", 40)
	nameB = strings.Repeat("Addison-Wesley Professional ", 40)
	sink  bool
)

func BenchmarkCompareStrings(b *testing.B) {
	a, c := string([]byte(nameA)), string([]byte(nameB))
	for b.Loop() {
		sink = a == c
	}
}

func BenchmarkCompareHandles(b *testing.B) {
	a, c := unique.Make(nameA), unique.Make(nameB)
	for b.Loop() {
		sink = a == c
	}
}

func BenchmarkMakeExisting(b *testing.B) {
	h := unique.Make(nameA) // the value is interned and stays alive
	for b.Loop() {
		sink = unique.Make(nameB) == h
	}
}

goos: darwin
goarch: arm64
pkg: example.com/shelf/uqbench
cpu: Apple M5
BenchmarkCompareStrings-10    	48637474	        28.70 ns/op	       0 B/op	       0 allocs/op
BenchmarkCompareHandles-10    	341559217	         3.608 ns/op	       0 B/op	       0 allocs/op
BenchmarkMakeExisting-10      	15053124	        76.52 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	example.com/shelf/uqbench	3.842s

package main

import (
	"fmt"
	"runtime"
	"strconv"
	"time"
	"unique"
)

func heapKiB() uint64 {
	runtime.GC()
	var m runtime.MemStats
	runtime.ReadMemStats(&m)
	return m.HeapAlloc >> 10
}

func main() {
	base := heapKiB()

	handles := make([]unique.Handle[string], 0, 300_000)
	for i := range 300_000 {
		handles = append(handles, unique.Make("member-"+strconv.Itoa(i)))
	}
	fmt.Println("interned, heap grew by KiB:", heapKiB()-base)
	runtime.KeepAlive(handles)

	// Drop every handle: the canonical copies become unreachable and the
	// package reclaims them (and its internal map entries) on later cycles.
	handles = nil
	for range 20 {
		runtime.GC()
		time.Sleep(10 * time.Millisecond)
	}
	fmt.Println("handles dropped, heap grew by KiB:", heapKiB()-base)
}

interned, heap grew by KiB: 65513
handles dropped, heap grew by KiB: 22