Skip to content

Commit 5dd24de

Browse files
committed
Improve README/documentation with more technical information
1 parent 9da31d6 commit 5dd24de

3 files changed

Lines changed: 31 additions & 3 deletions

File tree

README.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,34 @@ Let us also mention original projects handling this task and without which this
3333
- [maligned](https://github.com/mdempsky/maligned) from **Matthew Dempsky**
3434
- [structslop](https://github.com/orijtech/structslop) from **orijtech**
3535

36+
## Deep dive
37+
38+
There are two main tasks that `betteralign` does:
39+
40+
1. Create a candidate layout order by sorting fields by **descending alignment** required (reducing holes/padding between struct fields),
41+
2. Reduce **pointer bytes scanned** by GC ([GC will stop scanning values](https://go.dev/doc/gc-guide) at the last pointer in the value).
42+
43+
So having in mind those two tasks, field sort is performed the following way:
44+
45+
1. **Zero sized** objects are placed before non-zero sized objects,
46+
2. More **tightly aligned** objects are placed before less tightly aligned objects,
47+
3. **Pointerful objects** are placed before pointer-free objects,
48+
4. If both objects have pointers, objects with less **trailing non-pointer objects** are placed earlier,
49+
5. Lastly, order by **size**.
50+
51+
In case of the following:
52+
53+
```golang
54+
package foo
55+
56+
type IPAddr struct {
57+
Zone string // 16 bytes, 8-byte aligned
58+
IP []byte // 24 bytes, 8-byte aligned
59+
}
60+
```
61+
62+
Reason why `Zone` gets to be the first field is because trailing data comparison: `Sizeof(string) - ptrdata(string) = 8` vs `Sizeof([]byte) - ptrdata([]byte) = 16`, causing `string` field type to go first in struct `IPAddr` having less trailing non-pointer data.
63+
3664
## Installation
3765

3866
There are two ways of installing betteralign:

go.mod

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ require (
77
github.com/google/renameio/v2 v2.0.2
88
github.com/sirkon/dst v0.26.4
99
go.uber.org/automaxprocs v1.6.0
10-
golang.org/x/tools v0.40.0
10+
golang.org/x/tools v0.41.0
1111
gotest.tools/v3 v3.5.2
1212
)
1313

go.sum

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ golang.org/x/mod v0.32.0 h1:9F4d3PHLljb6x//jOyokMv3eX+YDeepZSEo3mFJy93c=
2424
golang.org/x/mod v0.32.0/go.mod h1:SgipZ/3h2Ci89DlEtEXWUk/HteuRin+HHhN+WbNhguU=
2525
golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
2626
golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
27-
golang.org/x/tools v0.40.0 h1:yLkxfA+Qnul4cs9QA3KnlFu0lVmd8JJfoq+E41uSutA=
28-
golang.org/x/tools v0.40.0/go.mod h1:Ik/tzLRlbscWpqqMRjyWYDisX8bG13FrdXp3o4Sr9lc=
27+
golang.org/x/tools v0.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc=
28+
golang.org/x/tools v0.41.0/go.mod h1:XSY6eDqxVNiYgezAVqqCeihT4j1U2CCsqvH3WhQpnlg=
2929
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
3030
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
3131
gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=

0 commit comments

Comments
 (0)