Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

runtime/cgo: document Handle better #45427

Closed
ainar-g opened this issue Apr 7, 2021 · 3 comments
Closed

runtime/cgo: document Handle better #45427

ainar-g opened this issue Apr 7, 2021 · 3 comments

Comments

@ainar-g
Copy link
Contributor

@ainar-g ainar-g commented Apr 7, 2021

CL 295369 (issue #37033) added the new type runtime/cgo.Handle. The documentation currently says:

Handle provides a safe representation of Go values to pass between Go and C. The zero value of a handle is not a valid handle, and thus is safe to use as a sentinel in C APIs.

But it doesn't mention what it means by an “unsafe” value. I assume that what it means is a reference to the “Passing pointers” section of the cgo documentation, but the example code that the package currently provides simply passes a [pointer to an] integer between Go and C.

I think that the code should be replaced with something better documented and closer to real-world scenarios, and also that perhaps direct links to the cgo documentation about which values are typically unsafe should be added.

@dmitshur dmitshur added this to the Go1.17 milestone Apr 7, 2021
@dmitshur
Copy link
Member

@dmitshur dmitshur commented Apr 7, 2021

@ianlancetaylor
Copy link
Contributor

@ianlancetaylor ianlancetaylor commented Apr 7, 2021

@ainar-g Please comment on https://golang.org/cl/308230. Thanks.

@gopherbot
Copy link

@gopherbot gopherbot commented Apr 7, 2021

Change https://golang.org/cl/308230 mentions this issue: runtime/cgo: clarify Handle documentation

@dmitshur dmitshur added NeedsFix and removed NeedsInvestigation labels Apr 7, 2021
@gopherbot gopherbot closed this in 7e58380 Apr 8, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants