How does GOMEMLIMIT change the heap goal Go's GC pacer computes, and why is it soft?

## The problem GOMEMLIMIT solves `GOGC` alone paces relative to the live heap. That is elegant and self-scaling, but it has no idea what machine the program is on. A ratio that behaves perfectly at a 100 MB live set will target a 4 GB heap once the live set reaches 2 GB, whether or not that much memory exists. `GOMEMLIMIT` adds the missing absolute number. ## How it enters the pacing calculation With a limit configured, the runtime computes two candidate goals for the next cycle: 1. The `GOGC` goal, roughly `live heap x (1 + GOGC/100)`. 2. A limit-derived goal: the largest heap that still leaves total runtime memory beneath `GOMEMLIMIT`, after subtracting everything else the runtime is holding. It paces to the **smaller** of the two. That single rule explains most of the behaviour people find surprising: - Well below the limit, the `GOGC` goal is smaller and the limit is invisible - it changes nothing at all. - As the live set grows, the limit-derived goal falls until it drops beneath the `GOGC` goal, and from that point the limit is setting the pace. The effective growth ratio shrinks continuously; cycles get closer together and each reclaims less headroom. - Both knobs remain live simultaneously. Setting a memory limit does not disable `GOGC`, and vice versa. ## What counts against the limit The limit is not a heap limit. It covers **all memory the Go runtime manages**: the heap, goroutine stacks, globals, and the runtime's own metadata and internal structures. That makes it a much better proxy for a process's real footprint than a heap figure alone. Equally important is what it does *not* cover: memory the runtime does not account for. Allocations made through cgo, mappings the program makes for itself, and the binary's own text and data are outside it. A process whose footprint is dominated by such memory will breach any container limit while the Go runtime believes it is comfortably under its own. ## What "soft" means, exactly A hard limit would mean the runtime refuses allocations or aborts when the limit is reached. `GOMEMLIMIT` does neither. It is an aim, not an enforcement: - The runtime will collect more and more aggressively as memory approaches the limit. - If the **live** set alone exceeds the limit, there is nothing collection can do - that memory is reachable. The program keeps running, over the limit. - To prevent a program from being pinned in continuous, futile collection while trying, the runtime includes a **GC CPU limiter** that caps total garbage-collection CPU at 50%. When that cap binds, the collector effectively gives up on holding the line and lets the limit be exceeded rather than spending the whole machine on marking. That last mechanism is the reason a soft limit degrades rather than deadlocks. A hard limit would turn a memory-hungry moment into a crash; a soft one turns it into extra CPU, and then, when even that is bounded, into extra memory. ## Setting it `GOMEMLIMIT` is an environment variable taking a byte count with an optional unit suffix - `B`, `KiB`, `MiB`, `GiB` or `TiB` - and its default is effectively unlimited. The same value can be set and read from inside the program with `runtime/debug.SetMemoryLimit`, which is useful when the limit has to be derived at startup rather than known in advance. ## The mental model to keep Think of `GOGC` as a *ratio* and `GOMEMLIMIT` as a *ceiling*, with the pacer always obeying whichever is more restrictive at that moment. The ratio keeps the collector proportionate at any scale; the ceiling stops the ratio from writing cheques the machine cannot cash. Because the ceiling is soft, exceeding it is a signal about the live set rather than a fault to be caught - the collector has already done everything collection can do.