Chapter 12 Memory Allocator on Go: Under the Hood

12.1 Design Principles

Mon, 01 Jan 0001 00:00:00 +0000

12.1 Design Principles

By now we have seen how a Go program starts up, and how the scheduler spreads goroutines across operating-system threads for execution. The single thing that scheduled code does most often is request memory: every new, every local variable that escapes to the heap, every slice growth, all funnel into the same entry point, runtime.mallocgc. This chapter is about the allocator behind that entry point. This section does not yet touch its parts; it answers a question that comes first: what mutually pulling goals must a memory allocator built for Go satisfy, and on which few judgments does it settle them? Once you understand these trade-offs, the structures and paths in the following sections (12.2–12.6) will all have a clear origin.

12.2 Components

Mon, 01 Jan 0001 00:00:00 +0000

12.2 Components

12.1 described the allocator as a layered structure that is “lock-free on the fast path, locked on the slow path.” This section names and locates the few core components of that structure, and grounds them in their actual form in go1.26: what state each component carries, why it is designed the way it is, and how they chain together into a restocking pipeline. Once you have understood these few things, the later allocation paths (12.4–12.6) are just “a walk across this same picture.”

12.3 Initialization

Mon, 01 Jan 0001 00:00:00 +0000

12.3 Initialization

12.2 broke the allocator down into a few parts: mcache, mcentral, mheap, and arena. But that was a static picture. These parts do not fall into place on their own; they must be set up once, at the very start of the program. This section answers the question: when main has not yet run and the first new has not yet happened, what infrastructure does the runtime lay down for the allocator.

12.4 Large Object Allocation

Mon, 01 Jan 0001 00:00:00 +0000

12.4 Large Object Allocation

The allocation hierarchy of 12.2 was built for objects that are “small and frequent”: a per-P mcache, a mcentral shared by size class, and a global mheap. These three cache layers collapse the vast majority of allocations into a handful of lock-free bit operations. But this delicate machine carries an implicit premise, that the object is small enough to fit into a size class. Once an object exceeds maxSmallSize (32768 bytes in go1.26, that is 32KB), it no longer fits into any size class slot, and the whole replenishment chain loses its meaning for it.

12.5 Small Object Allocation

Mon, 01 Jan 0001 00:00:00 +0000

12.5 Small Object Allocation

Small objects are those whose size falls between 16B and 32KB (in go1.26, maxSmallSize = 32768). They are the most common kind of allocation in a Go program: a struct, the backing array of a modest slice, the result of a string concatenation, the vast majority land in this range. The path the allocator designs for them is the main stage of the mcache → mcentral → mheap hierarchy from 12.2, and it is where the whole allocator’s “lock-free fast path” design (12.1) makes good on its performance promise.

12.6 Tiny Object Allocation

Mon, 01 Jan 0001 00:00:00 +0000

12.6 Tiny Object Allocation

The previous two sections walked through the two ends of the allocator. Large objects (12.4) bypass the cache and ask the mheap for memory by the page directly; small objects (12.5) pull an equal-sized slot from the per-P mcache according to their size class. This section fills in the last and least conspicuous category of object, the tiny object: those smaller than 16 bytes and free of pointers. They are extremely numerous and individually tiny, so if each were also given a slot by size class, the waste would be astonishing. Go sets up a dedicated path for them, packing multiple tiny objects into the same block, and trades one simple “bump pointer” technique for sizable memory savings.

12.7 The Page Allocator

Mon, 01 Jan 0001 00:00:00 +0000

12.7 The Page Allocator

Beneath mheap (12.2), the component that answers “which pages are free, which are in use” is the page allocator. It is the foundation of the entire allocator: when an mcentral runs out of spans it asks mheap for new pages, large objects (12.4) are requested directly by page, and every page a span occupies is ultimately carved out from here. The page allocator must also return pages that have stayed idle for a long time back to the operating system. These two responsibilities, one tied to the speed of allocation and the other to the resident memory of the process, are exactly the most enduring tension in Go’s memory system.

12.8 Memory Statistics

Mon, 01 Jan 0001 00:00:00 +0000

12.8 Memory Statistics

The allocator keeps books while it works. Every time it wholesales a stretch of address space from the operating system, carves out a span, or allocates or sweeps an object, the runtime accumulates the corresponding count into a set of global variables (runtime.memstats). These books are not a statistical report compiled after the fact; they are a running ledger written down in passing during allocation and reclamation. They serve two ends. Outwardly, they let users and monitoring systems see the memory shape of the process. Inwardly, both the GC pacer (13.3) and the soft memory limit GOMEMLIMIT (12.7) must read these books to decide “at what heap size should the next round of reclamation be triggered.” In other words, the bookkeeping closes a feedback loop: allocation produces data, data drives decisions, and decisions in turn constrain allocation.

12.9 Past, Present, and Future

Mon, 01 Jan 0001 00:00:00 +0000

12.9 Past, Present, and Future

The allocator did not arrive fully formed. It has been polished over and over as Go evolved. Tracing this line of evolution makes clear which trade-offs the current design grew out of, and gives a glimpse of where it is headed. One judgment worth keeping in mind first: nearly every major change to the allocator was not made to make “allocation itself faster,” but to re-place a stone in the three-way game among allocation speed, memory footprint, and cooperation with the garbage collector. Once this main thread is read, the several rewrites below stop looking like isolated version trivia and become instead the same engineering problem being solved again and again.