How Slices Grow

Output:

len    1  cap    1
len    2  cap    2
len    3  cap    4
len    5  cap    8
len    9  cap   16
len   17  cap   35
len   36  cap   71
len   72  cap  151
len  152  cap  303
len  304  cap  575
len  576  cap 1023
len 1024  cap 1536
len 1537  cap 2304
Copy

The loop appends 1,600 items to one slice and prints a line each time the capacity changes. The capacity starts by doubling, then changes from 16 to 35, and later grows by much less than double. Nothing in the code asks for these numbers.

They come from a short rule in the runtime and from the sizes of the memory blocks that the allocator (the part of the runtime that reserves heap memory) uses. How does append choose a new capacity, what happens to other slices of the same array, and how can a small slice keep a large array in memory?

The Slice Header

A slice value is a small struct of three words, called the slice header. The words are a pointer to the first element, the length (how many elements are in use), and the capacity (how many elements fit before the array ends). On amd64 each word is 8 bytes, so unsafe.Sizeof of any slice reports 24 bytes, whatever the slice contains.

When append has room, it writes the new element into the existing array and returns a header with a larger length. When it has no room, it allocates a larger array, copies every existing element, and returns a header that points to the new array. Copying is the expensive part, and so the runtime grows the array by more than one element each time. An append therefore costs a constant amount on average, even though an individual append sometimes copies everything.

The Growth Rule

The function nextslicecap in runtime/slice.go chooses the requested capacity. This is the Go 1.27 code, shortened by removing the check for overflow, and it can change between releases.

func nextslicecap(newLen, oldCap int) int {
	newcap := oldCap
	doublecap := newcap + newcap
	if newLen > doublecap {
		return newLen
	}

	const threshold = 256
	if oldCap < threshold {
		return doublecap
	}
	for {
		newcap += (newcap + 3*threshold) >> 2
		if uint(newcap) >= uint(newLen) {
			return newcap
		}
	}
}
Copy

The rule has three cases:

1. If the new length is more than double the old capacity, as when appending many elements at once, the capacity is the new length.
2. If the old capacity is below 256, the capacity doubles.
3. Otherwise, the capacity repeatedly grows by a quarter of itself plus 192, which is the expression (newcap + 768) / 4, until the new length fits. The growth factor therefore changes gradually from 2 for small slices toward 1.25 for very large ones.

Rounding to Size Classes

The rule above gives only a first answer. The allocator serves small requests from fixed block sizes called size classes (for example 1,024, 1,152, and 2,304 bytes, listed in internal/runtime/gc/sizeclasses.go). A request is rounded up to the next class. The append function then sets the capacity to use the whole block, since the extra bytes would otherwise be wasted.

The Item type adds one more detail. An Item is 32 bytes and contains a string, and therefore a pointer. For a block over 512 bytes that contains pointers, the allocator stores an 8-byte header in the block that describes where the pointers are. That header is added before rounding and subtracted afterward (roundupsize in runtime/msize.go). A request above 32 KB has no such header, and it rounds up to a multiple of the 8 KB page (the unit in which the runtime manages heap memory) instead.

Three of the jumps from the opening program show the arithmetic:

An element type with no pointers skips the header. A slice of int64 that is stored in a package variable, so that it must live on the heap, shows this:

Output:

1 2 4 8 16 32 64 128 256 512 848 1280 1792
Copy

The change from 512 to 848 follows the same steps. The rule gives 512 + (512 + 768) / 4 = 832, which is 6,656 bytes, and the next size class is 6,784 bytes, which holds 848 values.

The package variable matters here. As of Go 1.27, a small slice that stays inside its function can start in a 32-byte buffer on the stack (growsliceBuf in runtime/slice.go). The same loop on a local []int64 therefore reports a first capacity of 4 instead of 1. Treat capacity as a value to read, never a value to predict. Code that depends on an exact growth sequence depends on details that the language does not promise.

Append and Aliasing

Two slices of one array share their elements, a situation called aliasing. Aliasing becomes dangerous with append, because when there is spare capacity it writes into the shared array without any warning. A third index in a slice expression prevents this. The full slice expression s[a:b:c] sets the capacity of the result to c - a.

Output:

after plain slice: [A-100 B-200 NEW-1 D-400]
after full slice:  [A-100 B-200 NEW-1 D-400]
limited: [CHANGED B-200 NEW-2] cap 4
Copy

The first append overwrote C-300 in the original slice, even though the call never names that element. The second append had no spare capacity, so it allocated a new array. Later changes to limited therefore do not affect skus.

This bug usually appears when a function returns part of an internal slice and the caller appends to the result. Returning s[a:b:b] from such a function stops append from overwriting the internal data, although the returned elements stay shared until an append copies them.