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

unsafe: document Sizeof() including "invisible overhead" #52018

Closed
jzelinskie opened this issue Mar 29, 2022 · 3 comments
Closed

unsafe: document Sizeof() including "invisible overhead" #52018

jzelinskie opened this issue Mar 29, 2022 · 3 comments
Labels
Documentation help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@jzelinskie
Copy link
Contributor

What version of Go are you using (go version)?

1.x

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

N/A

What did you do?

I read the documentation for unsafe.Sizeof().

What did you expect to see?

The detail that Sizeof() includes overhead such as headers or alignment padding as I discovered from reading https://groups.google.com/g/golang-nuts/c/TFUoKFUi96A/m/qJmq3sdLCwAJ

What did you see instead?

No mention of these lower-level details other than the clarification that Sizeof() does not chase pointers.

@ianlancetaylor
Copy link
Contributor

The documentation at https://pkg.go.dev/unsafe#Sizeof is accurate. Can you suggest some (brief) text that we could add to make it more clear? Thanks. (Note that the current implementations don't use any headers, and that alignment padding only applies to struct types.)

@ianlancetaylor ianlancetaylor added help wanted NeedsFix The path to resolution is known, but the work has not been done. labels Mar 29, 2022
@ianlancetaylor ianlancetaylor added this to the Backlog milestone Mar 29, 2022
@jzelinskie
Copy link
Contributor Author

Thanks for the quick response.

I think a fair amount of developers are probably unaware that alignment could cause unsafe.Sizeof() to return a value that isn't the sum of each field size.

In the past, I believe I've used unsafe.Sizeof() to debug the ordering of fields in my structs to save memory from misalignment (and add new ones at no cost!). It's been long enough that I forgot it had that behavior and rediscovered it again, but in a mailing list entry rather than the function documentation.

I think something as simple as adding this additional sentence would suffice:

Sizeof takes an expression x of any type and returns the size in bytes of a hypothetical variable v as if v was declared via var v = x. The size does not include any memory possibly referenced by x. For instance, if x is a slice, Sizeof returns the size of the slice descriptor, not the size of the memory referenced by the slice. The size also includes any padding introduced by struct alignment. The return value of Sizeof is a Go constant.

I think this is sufficient to highlight this "edge case" and provides enough context that a developer could search for "struct alignment" if they wanted to learn more.

@gopherbot
Copy link

Change https://go.dev/cl/397516 mentions this issue: unsafe: document that Sizeof includes field alignment

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

3 participants