Add introspection methods, stack traces, and RWMutex optimization

- Add Len() and Has() methods for cache introspection
- Add Cleanup() method to remove expired entries
- Include stack trace in PanicError for better debugging
- Use RWMutex with RLock fast path in DoUntil for better read performance

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: MagicalTux

unison.go

@@ -2,13 +2,15 @@ package unison
 
 import (
 	"fmt"
+	"runtime/debug"
 	"sync"
 	"time"
 )
 
-// PanicError wraps a panic value as an error.
+// PanicError wraps a panic value as an error, including the stack trace.
 type PanicError struct {
 	Value any
+	Stack []byte
 }
 
 func (e *PanicError) Error() string {
@@ -27,10 +29,47 @@ type call[T any] struct {
 // Group represents a class of work and forms a namespace in which
 // units of work can be executed with duplicate suppression.
 type Group[K comparable, T any] struct {
-	mu sync.Mutex
+	mu sync.RWMutex
 	m  map[K]*call[T]
 }
 
+// Len returns the number of entries currently in the group.
+// This includes both in-flight calls and cached results (which may be expired).
+func (g *Group[K, T]) Len() int {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+	return len(g.m)
+}
+
+// Has reports whether a key exists in the group with a valid (non-expired) entry.
+// Returns true if the key has an in-flight call or a cached result that hasn't expired.
+func (g *Group[K, T]) Has(key K) bool {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+	c, ok := g.m[key]
+	if !ok {
+		return false
+	}
+	// If it's done and expired, it's not valid
+	if c.done && time.Now().After(c.exp) {
+		return false
+	}
+	return true
+}
+
+// Cleanup removes all expired entries from the group.
+// This is useful for reclaiming memory when using DoUntil with many unique keys.
+func (g *Group[K, T]) Cleanup() {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	now := time.Now()
+	for key, c := range g.m {
+		if c.done && now.After(c.exp) {
+			delete(g.m, key)
+		}
+	}
+}
+
 // Forget removes a key from the group, causing future calls to execute
 // the function again even if a previous call is still in-flight.
 // Goroutines already waiting for the result will still receive it.
@@ -63,7 +102,7 @@ func (g *Group[K, T]) Do(key K, fn func() (T, error)) (val T, err error) {
 
 	defer func() {
 		if r := recover(); r != nil {
-			c.err = &PanicError{Value: r}
+			c.err = &PanicError{Value: r, Stack: debug.Stack()}
 		}
 		g.mu.Lock()
 		delete(g.m, key)
@@ -81,11 +120,32 @@ func (g *Group[K, T]) Do(key K, fn func() (T, error)) (val T, err error) {
 // Subsequent calls within the cache window return the cached result without
 // executing the function again.
 func (g *Group[K, T]) DoUntil(key K, dur time.Duration, fn func() (T, error)) (val T, err error) {
+	// Fast path: check for cached result with read lock
+	g.mu.RLock()
+	if g.m != nil {
+		if c, ok := g.m[key]; ok {
+			if c.done && !time.Now().After(c.exp) {
+				// cached and still valid
+				g.mu.RUnlock()
+				return c.val, c.err
+			}
+			if !c.done {
+				// in-flight, wait for it
+				g.mu.RUnlock()
+				c.wg.Wait()
+				return c.val, c.err
+			}
+		}
+	}
+	g.mu.RUnlock()
+
+	// Slow path: need write lock to create or replace entry
 	g.mu.Lock()
 	if g.m == nil {
 		g.m = make(map[K]*call[T])
 	}
 
+	// Double-check after acquiring write lock
 	if c, ok := g.m[key]; ok {
 		if c.done && time.Now().After(c.exp) {
 			// cached result has expired, remove it and continue to create new call
@@ -109,7 +169,7 @@ func (g *Group[K, T]) DoUntil(key K, dur time.Duration, fn func() (T, error)) (v
 
 	defer func() {
 		if r := recover(); r != nil {
-			c.err = &PanicError{Value: r}
+			c.err = &PanicError{Value: r, Stack: debug.Stack()}
 		}
 		g.mu.Lock()
 		c.exp = time.Now().Add(dur)

unison_test.go

@@ -389,3 +389,148 @@ func TestDoUntilPanicCached(t *testing.T) {
 		t.Errorf("number of calls = %d; want 1 (panic should be cached)", got)
 	}
 }
+
+func TestPanicErrorStack(t *testing.T) {
+	var g Group[string, string]
+	_, err := g.Do("key", func() (string, error) {
+		panic("test panic")
+	})
+	if err == nil {
+		t.Fatal("expected error from panic")
+	}
+	panicErr, ok := err.(*PanicError)
+	if !ok {
+		t.Fatalf("expected *PanicError, got %T", err)
+	}
+	if len(panicErr.Stack) == 0 {
+		t.Error("expected stack trace in PanicError")
+	}
+	// Verify stack trace contains relevant info
+	stackStr := string(panicErr.Stack)
+	if len(stackStr) < 100 {
+		t.Error("stack trace seems too short")
+	}
+}
+
+func TestDoUntilPanicErrorStack(t *testing.T) {
+	var g Group[string, string]
+	_, err := g.DoUntil("key", time.Second, func() (string, error) {
+		panic("test panic")
+	})
+	if err == nil {
+		t.Fatal("expected error from panic")
+	}
+	panicErr, ok := err.(*PanicError)
+	if !ok {
+		t.Fatalf("expected *PanicError, got %T", err)
+	}
+	if len(panicErr.Stack) == 0 {
+		t.Error("expected stack trace in PanicError")
+	}
+}
+
+func TestLen(t *testing.T) {
+	var g Group[string, int]
+
+	if g.Len() != 0 {
+		t.Errorf("Len = %d; want 0", g.Len())
+	}
+
+	g.DoUntil("key1", time.Minute, func() (int, error) { return 1, nil })
+	g.DoUntil("key2", time.Minute, func() (int, error) { return 2, nil })
+
+	if g.Len() != 2 {
+		t.Errorf("Len = %d; want 2", g.Len())
+	}
+}
+
+func TestHas(t *testing.T) {
+	var g Group[string, int]
+
+	// Empty group
+	if g.Has("key") {
+		t.Error("Has returned true for non-existent key")
+	}
+
+	// Add a cached entry
+	g.DoUntil("key", 100*time.Millisecond, func() (int, error) {
+		return 42, nil
+	})
+
+	if !g.Has("key") {
+		t.Error("Has returned false for existing key")
+	}
+
+	// Wait for expiration
+	time.Sleep(110 * time.Millisecond)
+
+	if g.Has("key") {
+		t.Error("Has returned true for expired key")
+	}
+}
+
+func TestHasInFlight(t *testing.T) {
+	var g Group[string, int]
+	started := make(chan struct{})
+	proceed := make(chan struct{})
+
+	go func() {
+		g.Do("key", func() (int, error) {
+			close(started)
+			<-proceed
+			return 42, nil
+		})
+	}()
+
+	<-started // Wait for goroutine to start
+
+	if !g.Has("key") {
+		t.Error("Has returned false for in-flight key")
+	}
+
+	close(proceed) // Let the goroutine finish
+}
+
+func TestCleanup(t *testing.T) {
+	var g Group[string, int]
+	var calls atomic.Int32
+
+	fn := func() (int, error) {
+		return int(calls.Add(1)), nil
+	}
+
+	// Create some cached entries
+	g.DoUntil("key1", 50*time.Millisecond, fn)
+	g.DoUntil("key2", 50*time.Millisecond, fn)
+	g.DoUntil("key3", 200*time.Millisecond, fn)
+
+	if g.Len() != 3 {
+		t.Errorf("Len = %d; want 3", g.Len())
+	}
+
+	// Wait for some to expire
+	time.Sleep(60 * time.Millisecond)
+
+	// Cleanup should remove expired entries
+	g.Cleanup()
+
+	if g.Len() != 1 {
+		t.Errorf("Len after Cleanup = %d; want 1", g.Len())
+	}
+
+	// key3 should still be there
+	if !g.Has("key3") {
+		t.Error("key3 should still exist after cleanup")
+	}
+}
+
+func TestCleanupEmpty(t *testing.T) {
+	var g Group[string, int]
+
+	// Should not panic on empty group
+	g.Cleanup()
+
+	if g.Len() != 0 {
+		t.Errorf("Len = %d; want 0", g.Len())
+	}
+}