Dig101 — struct memory alignment in Go

Contents

  1. 1. 0x01 Why align?
  2. 2. 0x02 Data structure alignment
    1. 2.1. Size guarantees
    2. 2.2. Alignment guarantees
  3. 3. 0x03 Zero-size fields
  4. 4. 0x04 Address alignment
  5. 5. 0x05 Safe 64-bit access
    1. 5.1. Why
    2. 5.2. How
    3. 5.3. Or use a mutex

Update: slides from Go Night Reading #588


Dig101: dig more, simplify more, know more

Strings, slices, and maps all lean on structs under the hood. Here: struct memory alignment — handy when reading stdlib code and shaving wasted padding.

A few terms first:

  • Word — the natural data unit for the machine (machine word); the chunk the CPU often moves in one step.
  • Word size — bits per word (often 16 / 32 / 64 today; on many systems word size in bytes is N/8 for N-bit CPUs).

Registers, CPU↔memory transfers, and many addresses are word-oriented. See Word (computing).

0x01 Why align?

CPUs do not read memory byte-by-byte; they access at 2/4/8-byte (etc.) granularities.

If address and size are n-byte aligned, one transfer suffices; otherwise the hardware does extra work.

0x02 Data structure alignment

Size guarantees

From Size and alignment guarantees:

type size (bytes)
byte, uint8, int8 1
uint16, int16 2
uint32, int32, float32 4
uint64, int64, float64, complex64 8
complex128 16

A struct or array type has size zero if it contains no fields (or elements) larger than zero. Two distinct zero-size variables may share the same address.

struct{} and [0]T have size 0; distinct zero-size vars may share an address.

Alignment guarantees

  • For any variable x: unsafe.Alignof(x) ≥ 1.
  • For struct x: Alignof(x) is the max of field alignments, at least 1.
  • For array x: same as element type alignment.
type alignment
bool, byte, uint8, int8 1
uint16, int16 2
uint32, int32 4
float32, complex64 4
arrays element type
structs fields
other types one machine word

On 32-bit, a machine word is 4 bytes; on 64-bit, 8.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
type T1 struct {
a [2]int8
b int64
c int16
}
type T2 struct {
a [2]int8
c int16
b int64
}
fmt.Printf("arrange fields to reduce size:\n"+
"T1 align: %d, size: %d\n"+
"T2 align: %d, size: %d\n",
unsafe.Alignof(T1{}), unsafe.Sizeof(T1{}),
unsafe.Alignof(T2{}), unsafe.Sizeof(T2{}))
/*
output:
arrange fields to reduce size:
T1 align: 8, size: 24
T2 align: 8, size: 16
*/

On amd64, max field alignment is 8. T1 pads after a and after c → 24 bytes. Reordering to T2 packs a+c then one pad before b → 16 bytes.

Reordering fields can cut padding.

0x03 Zero-size fields

struct{} has size 0. As a non-final field it adds no padding; as the final field the compiler still pads the struct.

Why? A pointer to that final zero field would point past the struct’s storage; if that pointer outlives the struct, you leak unrelated memory.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
type T1 struct {
a struct{}
x int64
}

type T2 struct {
x int64
a struct{}
}
a1 := T1{}
a2 := T2{}
fmt.Printf("zero size struct{} in field:\n"+
"T1 (not as final field) size: %d\n"+
"T2 (as final field) size: %d\n",
unsafe.Sizeof(a1), // 8
unsafe.Sizeof(a2)) // 16 on 64-bit, 12 on 32-bit

0x04 Address alignment

Package unsafe:

Addresses may need to be multiples of Alignof(T). For variable x: uintptr(unsafe.Pointer(&x)) % unsafe.Alignof(x) == 0.

sync.WaitGroup exploits this:

1
2
3
4
5
6
7
8
9
10
11
12
type WaitGroup struct {
noCopy noCopy
state1 [3]uint32
}

func (wg *WaitGroup) state() (statep *uint64, semap *uint32) {
if uintptr(unsafe.Pointer(&wg.state1))%8 == 0 {
return (*uint64)(unsafe.Pointer(&wg.state1)), &wg.state1[2]
} else {
return (*uint64)(unsafe.Pointer(&wg.state1[1])), &wg.state1[0]
}
}

state1 is three uint32s. On 64-bit, uint32 is 4-aligned, so state1 is at 4N.

  • If 4N is also 8-aligned (N even), the first 8 bytes are a valid *uint64.
  • If not (N odd), bytes [1:9] are 8-aligned.

The spare 4 bytes hold sema.

Why force 64-bit alignment on 32-bit? So uint64 can be updated atomically.

0x05 Safe 64-bit access

sync/atomic BUG note: on x86-32, ARM (non-Linux), and 32-bit MIPS, you must 8-align uint64 used with atomic ops (Pentium MMX+ on x86-32, etc.).

Why

uint64 is 8 bytes. On 32-bit, alignment is 4 → the value can span two words; a non-atomic pair of loads/stores is racy. issue #6404 shows int64 after bool only 32-bit aligned.

How

The first word in a variable or in an allocated struct, array, or slice can be relied upon to be 64-bit aligned.

“Allocated” = declared, make, new.

On GOARCH=386, safe examples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
var c0 int64
atomic.AddInt64(&c0, 1)

c1 := [5]int64{}
atomic.AddInt64(&c1[:][0], 1)

c2 := struct {
val int64 // pos 0
val2 int64 // pos 8
valid bool // pos 16
}{}
atomic.AddInt64(&c2.val, 1)
atomic.AddInt64(&c2.val2, 1)

type T struct {
val2 int64
_ int16
}
c3 := struct {
val T
valid bool
}{}
atomic.AddInt64(&c3.val.val2, 1)

c4 := struct {
val int64
valid bool
_ [4]byte // or _ uint32 — pad on 32-bit
val2 int64
}{}
atomic.AddInt64(&c4.val2, 1)

c5 := struct {
val int64
valid bool
val2 []int64
}{val2: []int64{0}}
atomic.AddInt64(&c5.val2[0], 1)

Slice data lives on the heap and is aligned; embedded arrays of structs are not — this panics:

1
2
3
4
5
6
c51 := struct {
val int64
valid bool
val2 [3]int64
}{val2: [3]int64{0}}
atomic.AddInt64(&c51.val2[0], 1) // panic

Heap pointer to int64:

1
2
3
4
5
6
c6 := struct {
val int64
valid bool
val2 *int64
}{val2: new(int64)}
atomic.AddInt64(c6.val2, 1)

Caveat: a 12-byte struct whose first field is int64 may still fail alignment — issue #37262.

Or use a mutex

1
2
3
4
5
6
7
8
c := struct{
val int16
val2 int64
}{}
var mu sync.Mutex
mu.Lock()
c.val2 += 1
mu.Unlock()

Why not uint64 in WaitGroup directly? Embedding WaitGroup anywhere but the first field would break alignment guarantees.

Takeaways

  • Alignment speeds memory access.
  • Address of x: uintptr(unsafe.Pointer(&x)) % Alignof(x) == 0.
  • Reorder fields to shrink structs; avoid trailing struct{}.
  • On 32-bit, 8-align uint64 for atomics — or use a mutex.

Tools: dominikh/go-tools (structlayout, structlayout-optimize, structlayout-pretty).

Code: NewbMiao/Dig101-Go

See also: Golang memory alignment

Questions? Leave a comment below or email: newbvirgil@gmail.com