Implement register-based closure ctx

[cpunion]

Summary

This PR implements a register-based closure context (ctx) mechanism to significantly improve closure call performance by avoiding TLS/global memory access when possible. This addresses issue #1497.

Background

Previously, closure contexts were passed exclusively through a global or TLS slot, which required memory loads on every closure call. This approach worked but had performance overhead and potential thread-safety issues in certain scenarios.

Changes

Core Implementation

1. Architecture-Specific Reserved Registers

   • Added per-architecture reserved registers for closure ctx:
     • amd64: r12
     • arm64: x26
     • 386: esi
     • riscv64: x27
     • Other platforms fall back to TLS/global

2. Closure Representation

   • Maintains {fn: *func, data: unsafe.Pointer} layout
   • fn: original Go signature (no explicit ctx parameter)
   • data: nil for plain functions, heap-allocated context for free variables

3. Calling Convention

   • Before call: write_ctx(data) - writes to reserved register or fallback
   • Callee reads ctx at function entry (if needed) and caches in local
   • After call: restore_ctx() - restores previous ctx to avoid corrupting caller
   • This is critical for nested closures and callbacks that may re-enter Go

4. Register Preservation

   • Added -ffixed-* flags to clang to prevent LLVM register allocation from clobbering the ctx register
   • Applies to both native use() and UseTarget() paths

5. Wrapper Functions

   • Only created for adaptation cases:
     • Legacy explicit-ctx functions: __llgo_stub.<fn>$ctx
     • Raw function pointers: __llgo_stub._llgo_func$<hash>
   • Regular function declarations are not wrapped

Test Coverage

Added comprehensive test cases in cl/_testgo/ and cl/_testcall/:

• Basic closure calls
• Nested closures (including sync.Once.Do patterns)
• Interface method closures
• Goroutine with closures
• Defer with closures
• Reflect-based closures
• C function calls within closures (register pollution tests)
• Closure value passing
• Method expressions and values

Documentation

Updated doc/closure.md with:

• Design goals and rationale
• Representation details
• Calling convention
• Architecture-specific register mapping
• Performance considerations

Performance Impact

• Reduced closure call overhead by eliminating TLS/global memory access on supported platforms
• Thread-local on supported OSes with TLS fallback
• Bare-metal/wasm falls back to process-global slot

Testing

All existing tests pass. New test cases specifically validate:

• Closure context preservation across nested calls
• Register pollution scenarios (C function calls, nested closures)
• Interface method closures
• Goroutine safety with closures
• sync.Once and sync.WaitGroup compatibility

Issue References

Fixes #1497

[gemini-code-assist]

Note

The number of changes in this pull request is too large for Gemini Code Assist to generate a summary.

[xgopilot]

Code Review Summary

This PR implements a well-designed register-based closure context mechanism. The architecture is sound with appropriate register selection (callee-saved registers), proper save/restore semantics, and comprehensive test coverage.

Strengths:

• Comprehensive test coverage across all closure patterns
• Register pollution tests for both C interop and nested closures
• Proper thread safety through per-goroutine register isolation
• Efficient wrapper generation with tail call optimization

Minor Issues to Address:

• Unused noop() function in regpollute/in.go
• Missing direct method call tests in go/in.go vs defer/in.go
• Documentation could clarify wrapper naming variations

Overall, this is a solid implementation ready for merge after addressing minor issues.

[xgopilot]

This noop() function is declared but never used in the test file. Consider either removing it or adding a test case that uses it (e.g., a noop call between closure operations to test register preservation across non-closure calls).

[xgopilot]

For consistency with defer/in.go, consider adding direct method call tests:

// go with direct method call (not via method value)
go s.Add(7)
go sv.Inc(8)

The defer test includes these (lines 63-64), so having parity would ensure the go statement handles direct method calls the same way.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.66%. Comparing base (f6337d4) to head (a6aef86).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1568      +/-   ##
==========================================
- Coverage   91.01%   89.66%   -1.36%     
==========================================
  Files          45       46       +1     
  Lines       11971    12213     +242     
==========================================
+ Hits        10896    10951      +55     
- Misses        899     1075     +176     
- Partials      176      187      +11     

☔ View full report in Codecov by Sentry.
📢 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.