How does Go's runtime decide how much marking work an allocating goroutine owes as a mark assist?

### What has to be true by the end of the cycle Concurrent marking has a deadline: the mark phase must finish before the heap grows past the size at which this cycle was meant to complete. The runtime therefore has two quantities it can compare at any instant — how much scan work remains, and how much allocation it expects before the deadline. Their ratio is the price of allocating: **scan work owed per byte allocated**. That number is the assist ratio, and the collector recomputes it as the cycle proceeds. When marking is comfortably ahead, the ratio is small or the assist path never triggers; when marking is behind, the ratio climbs and allocation gets expensive. ### Assist credit, denominated in bytes Every goroutine carries a small piece of accounting state: its assist credit, a signed byte count (the `gcAssistBytes` field on the runtime's goroutine structure). Think of it as a prepaid balance of allocation. Each allocation debits that balance. While the balance stays non-negative, the allocation is as cheap as it ever is — the fast path in the allocator just subtracts and returns. When the balance goes negative, the goroutine is in debt, and the runtime diverts it into `runtime.gcAssistAlloc` before the object is handed back. Note what is being counted. The charge is proportional to **bytes**, not to the number of allocations. A thousand tiny structs and one large buffer of the same total size owe roughly the same assist. This is what makes the mechanism a genuine brake on allocation *volume* rather than a per-call tax. ### Repaying the debt Inside the assist path the goroutine becomes, briefly, a mark worker. It pulls objects from the collector's work queues and scans them — following their pointer fields, marking what they reach — through `runtime.gcDrainN`, which drains a bounded amount of work rather than draining until the queues are empty. Once it has scanned enough to bring its credit back to non-negative, it leaves the assist path and its allocation completes. The important property is that this is *inline*, synchronous, and on the goroutine's own stack. It is not deferred to a helper and it is not a pause: the rest of the program is untouched. ### Over-assisting, and why Entering and leaving the assist machinery costs meaningfully more than scanning a handful of objects. If the runtime charged exactly the debt every time, a hot allocation loop would bounce in and out of the assist path continuously. So an assisting goroutine deliberately scans a fixed chunk of work larger than what it strictly owes, and the surplus is banked as positive credit. The next several allocations then run on the fast path, spending that credit, until the balance goes negative again. The visible effect is that assist cost arrives in occasional lumps rather than as a smooth per-allocation tax — which is another reason the symptom shows up in the tail of a latency distribution rather than in the average. ### Borrowing from the background workers Assists are the collector's fallback, not its primary strategy, and the runtime works hard to keep them rare. Background mark workers that complete more scan work than their own share is accounted for flush the surplus into a shared credit bank. A goroutine that finds itself in debt checks that bank first: if there is enough banked credit, it takes what it needs and its allocation proceeds without scanning anything at all. In a well-paced cycle on a service with moderate allocation, this is the common case — goroutines dip into debt, take credit the background workers have already earned, and never actually scan. Assists only bite when the background workers themselves cannot keep ahead. ### The stall There is one more state, and it is the "stall" half of the picture. A goroutine can owe work, have no credit of its own, find no banked credit, and find no marking work it can perform right now — for example, the work queues are momentarily drained but the cycle has not been declared complete. It cannot proceed (that would let allocation outrun marking) and it cannot pay (there is nothing to do). So it parks on the runtime's assist queue and is woken when credit is flushed by a background worker or when the cycle ends. A goroutine in that state is not burning CPU; it is blocked, and it looks like latency with no matching CPU time anywhere in the process — a genuinely confusing signature if you do not know the mechanism exists. ### Practical consequences - The knobs that matter to you are the ratio's two halves: how much scan work your heap creates (pointer density, live-object count) and how many bytes you allocate per unit of useful work. - Assist cost is not uniform across requests. It is concentrated on whichever goroutine happens to allocate when the collector is furthest behind. - Because credit is per goroutine and banked in chunks, the cost distribution is lumpy by design; averaging it away hides it.