docs: clarify avalue double indirection for out-pointer parameters - #80
Merged
Merged
Conversation
…loses #79) Add comprehensive documentation of the avalue pointer-to-value convention in three places: - ffi/ffi.go godoc: avalue Convention section with WRONG/CORRECT examples - README.md: new 'avalue Convention' section with out-pointer pattern - docs/ARCHITECTURE.md: avalue Indirection Convention in Type System section Also update package doc: fix stale platform list and performance numbers.
kolkov
force-pushed
the
docs/struct-examples
branch
from
September 9, 2026 09:17
f8e2ab7 to
1b765fb
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
3 of 5 tasks
unxed
pushed a commit
to unxed/goffi
that referenced
this pull request
Sep 25, 2026
Port of upstream go-webgpu/goffi 8636646 (go-webgpu#80, closes go-webgpu#79): avalue[i] is a pointer TO the argument value, so a C out-pointer parameter (T *out) needs an intermediate variable, outPtr := unsafe.Pointer(&out), passed as unsafe.Pointer(&outPtr). Passing &out directly hands C the current value of out -- usually NULL. Documented, with the wrong and the right form, in the ffi package doc, README and docs/ARCHITECTURE.md. Adapted rather than taken verbatim in ffi/ffi.go: - the package doc's platform list follows this fork's docs/PLATFORMS.md (adds NetBSD and Windows 386) instead of upstream's "8 production targets"; - the Performance paragraph is left as it was: upstream replaced it with its own benchmark figures, which were not measured here; - the "Use runtime.Pinner to pin pointers under a moving GC" line that upstream dropped from CallFunctionContext's safety notes is kept. (cherry picked from commit 8636646)
unxed
added a commit
to unxed/goffi
that referenced
this pull request
Sep 25, 2026
…rk main Upstream go-webgpu#78 added its own goffi_static. The fork already has one, and Profile U and goffi_musl are built on it (ffi.Available, internal/static, callback_static.go, ffi.ErrStaticBuild). The two are equivalent for callers: LoadLibrary/GetSymbol return a *LibraryError wrapping ffi.ErrStaticBuild, the ELF has no PT_INTERP or DT_NEEDED, and errno capture is off. So the code keeps the fork's implementation: - conflicting .go/.s files and upstream's build-tag-only edits resolve to the fork's version; - upstream-only static files that would duplicate the fork's definitions are dropped: ffi/dl_static.go, ffi/errors_static.go, ffi/fakecgo_static.go, internal/fakecgo/static.go and asm_static_{amd64,arm64}.s; - upstream's ffi/static_test.go is kept, restricted to linux, where the fork's static mode applies (it is a no-op on Windows and Android). Taken from upstream: scripts/check-elf-linking.sh and the elf-linking CI job (added to ci-success next to platform-matrix), ADR-001, the v0.6.4 CHANGELOG/ROADMAP/README entries, the linking-modes docs (with rows for goffi_musl and the universal build), and the package doc changes. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Document the avalue pointer-to-value convention with focus on the non-obvious out-pointer case. Updated in three places:
ffi/ffi.gogodoc — avalue Convention section with WRONG/CORRECT examplesREADME.md— new section with out-pointer pattern and rule of thumbdocs/ARCHITECTURE.md— avalue Indirection Convention in Type SystemAlso fixes stale package doc (platform list, performance numbers).
The Problem
Discovered while building NVIDIA NVML bindings via GoFFI on Windows.
Test plan
go build ./...— cleango test ./...— all passCloses #79