perf: zero-allocation FFI + ABI-safe struct layout (v0.5.4)

[kolkov]

Summary

• Zero-allocation FFI — //go:noescape on runtime_cgocall eliminates 1 heap allocation (208–248 bytes) per call on all Unix platforms. syscallArgs stays on goroutine stack. Expected 10–25% perf improvement (Add //go:noescape to runtime_cgocall to eliminate per-call allocation #54)
• ABI-safe struct layout — structs.HostLayout (Go 1.23+) added to all 8 assembly-interface structs, guaranteeing C ABI memory layout against future Go compiler optimizations (Use Go 1.23's structs.HostLayout in ABI-boundary structures #55)
• Public docs updated (README, ARCHITECTURE, PERFORMANCE, CHANGELOG)

Details

Issue #54: //go:noescape

3 files changed — added //go:noescape between //go:linkname and func runtime_cgocall:

File	Path	Impact
HOT PATH	internal/syscall/syscall_unix_amd64.go	208 bytes/call saved
HOT PATH	internal/syscall/syscall_arm64.go	248 bytes/call saved
cold path	internal/dl/dl_unix.go	consistency

Safety verified: runtime.asmcgocall itself has //go:noescape in runtime/stubs.go:310. purego lacks this — compensates with sync.Pool.

Issue #55: structs.HostLayout

8 structs across 5 files — _ structs.HostLayout as first field (zero-sized, no offset change):

Struct	File	Risk without HostLayout
syscallArgs (AMD64)	internal/syscall/syscall_unix_amd64.go	HIGH — hardcoded asm offsets
syscallArgs (ARM64)	internal/syscall/syscall_arm64.go	HIGH — hardcoded asm offsets
dlopenArgs/dlsymArgs/dlerrorArgs	internal/dl/dl_unix.go	HIGH — hardcoded asm offsets
callbackArgs (AMD64)	ffi/callback.go	LOW — go_asm.h symbols
callbackArgs (ARM64)	ffi/callback_arm64.go	LOW — go_asm.h symbols
G, ThreadStart	internal/fakecgo/libcgo.go	LOW — Go field access

Issue #55 listed 4 structs — we found 8 (the highest-risk ones were missing).

Test plan

• go fmt ./... — clean
• go build ./... — clean
• go test ./... — all pass
• go vet ./... — only known dl_windows.go false positives
• golangci-lint run — 0 issues (exit 7 = Go 1.25 noise)
• Cross-compile all 8 platforms ✅
• CI green (Linux, macOS, Windows × CGO=0/1)
• Benchmark on Unix (go test -bench=. -benchmem ./ffi) — expecting 0 allocs/op

Closes #54, closes #55

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!