Performance optimizations for hot paths and stack trace handling

[samber]

Summary

This PR improves performance across multiple hot paths in the dependency injection container and stack trace handling, with a focus on reducing lock contention, allocations, and unnecessary work in frequently-called operations.

Key Changes

Stack Trace Optimization

• Refactored NewFrameFromCaller() to use runtime.Callers() and runtime.CallersFrames() instead of repeated runtime.Caller() calls, which re-walk the stack on each iteration
• Implemented a two-phase approach: first try a small batch of frames (4), then fall back to full capture (10) only if needed
• Extracted frame filtering logic into findEligibleFrame() helper for clarity
• Added caching for $GOPATH directory splitting and sorting in removeGoPath() to avoid repeated work when the environment variable hasn't changed (re-reads $GOPATH each call, so runtime mutation still works)

DAG and Service Resolution

• Added fast path in DAG.addDependency() with read lock check before acquiring write lock, reducing serialization for repeated invocations through transient/alias services
• Introduced DAG.servicesWithoutDependents() method that batches dependency checks under a single lock, replacing repeated explainService() calls during parallel shutdown
• Optimized Scope.Ancestors() to pre-allocate the result slice and walk the parent chain once, replacing recursive calls

Service Instance Caching

• Added fast-path read lock in serviceLazy.getInstance() to check if instance is already built before acquiring write lock
• Applied same optimization to serviceAlias.getInstance() and serviceEager.getInstance()
• Added defensive atomic.LoadUint32() check before atomic.AddUint32() to avoid contended read-modify-write once frame collection cap is reached

Scope and Lifecycle

• Optimized Scope.onServiceInvoke() with fast-path read lock to avoid write lock on subsequent invocations
• Refactored RootScope.queueServiceHealthcheck() to handle non-expiring contexts more efficiently and avoid unnecessary channel wrapping

Utilities

• Improved orderedUniq() with pre-allocated slice and map based on input length
• Optimized newUUID() to use hex.Encode() with a fixed buffer instead of fmt.Sprintf(), reducing allocations

Testing

• Added a comprehensive benchmark suite in a dedicated bench/ package, exercising the library exclusively through its public API (invocation, registration, lifecycle, introspection, and stack-frame capture)
• A goleak TestMain keeps the goroutine-leak check on the health-check and shutdown benchmarks

Benchmark Results

Baseline (master) vs this branch, measured with the bench/ suite via benchstat. Runs were interleaved over 6 rounds (n=12 each) to average out CPU drift on the shared CI host (-benchmem -benchtime=100ms -count=2 per round; Go 1.24, linux/amd64).

Benchmark	time	allocs/op
InvokeLazySteadyState	−10.5%	6 (unchanged)
InvokeNamed	−18.7%	4 (unchanged)
InvokeTransient	−4.6%	6 (unchanged)
InvokeAlias	−18.7%	9 (unchanged)
InvokeAs	−3.5%	11 (unchanged)
InvokeNestedScopes	−8.7%	6 (unchanged)
ProviderChainTransient	−19.7%	24 (unchanged)
Provide	−18.6%	1426 → 1021 (−28%)
New	−34.1%	16 → 11 (−31%)
HealthCheck	−27.7%	625 → 475 (−24%)
Shutdown	−28.2%	946 → 546 (−42%)
ListProvidedServices	−25.3%	166 → 117 (−30%)
Ancestors	−88.8%	14 → 1 (−93%)
NewFrameFromCaller	−30.3%	6 → 2 (−67%)
NewFrameFromPC	−29.4%	1 → 0 (−100%)
geomean	−27.9%

All deltas are statistically significant (p < 0.001, except InvokeAs at p = 0.03). Steady-state invocation byte/alloc counts are unchanged — the remaining per-invoke allocations come from the invoker chain and virtual scope required for circular-dependency detection — so those wins come from reduced lock contention and cheaper hot-path work rather than fewer allocations. InvokeLazyParallel is omitted: the shared CI CPU makes the parallel measurement too noisy to report reliably (allocations are unchanged).

Notable Implementation Details

• All optimizations maintain thread-safety and correctness
• Fast-path optimizations use read locks before write locks to reduce contention in steady state
• Stack trace improvements reduce both CPU and allocations for frame discovery
• Shutdown optimization reduces lock acquisitions during parallel service shutdown by batching dependency checks

https://claude.ai/code/session_019ESFVztuAbfjQv9N9dJnXZ

[codecov]

Codecov Report

❌ Patch coverage is 90.42553% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.94%. Comparing base (303f9cf) to head (0f2d855).

Files with missing lines	Patch %	Lines
stacktrace/stacktrace.go	65.00%	5 Missing and 2 partials ⚠️
dag.go	86.66%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #247      +/-   ##
==========================================
+ Coverage   89.93%   89.94%   +0.01%     
==========================================
  Files          23       23              
  Lines        2155     2217      +62     
==========================================
+ Hits         1938     1994      +56     
- Misses        183      188       +5     
- Partials       34       35       +1     

Flag	Coverage Δ
unittests	89.94% <90.42%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.