Stack ou heap? Entendendo o escape analysis do Go

No artigo sobre zero values e pointer semantics eu terminei falando que, em Go, tudo é passado por valor, inclusive ponteiros. Ficou faltando responder uma pergunta que aparece logo em seguida: se eu pego o endereço de uma variável local e devolvo esse endereço, o que impede o dado de sumir quando a função retorna?

Em C, isso é um bug clássico:

int *broken(void) {
    int x = 42;
    return &x; // ponteiro pendurado: x morre com o frame
}

Em Go, o equivalente é código idiomático e aparece em praticamente todo construtor que você já escreveu:

func NewCounter() *Counter {
    c := Counter{}
    return &c // isso é normal em Go
}

Os dois programas parecem fazer a mesma coisa, mas só um deles funciona. A diferença é uma etapa do compilador chamada escape analysis, e ela é o que permite que Go tenha ponteiros sem ter as armadilhas de ponteiros.

A proposta deste artigo é ir do porquê ao como: primeiro por que stack e heap custam diferente, depois como o compilador decide entre as duas, como enxergar essa decisão com suas próprias ferramentas, quais padrões de código realmente causam escape e, no fim, o que fazer (e o que não fazer) com essa informação.

Duas regiões de memória, dois custos bem diferentes

Antes de falar da decisão, vale entender por que ela importa.

A stack é uma região por goroutine. Ela funciona em LIFO: chamou função, empilhou um frame; retornou, desempilhou. Alocar espaço na stack é somar um número a um registrador, e liberar é subtrair. Não existe fragmentação, não existe busca por espaço livre e, principalmente, o coletor de lixo não precisa saber nada sobre isso. Quando a função retorna, a memória já era.

O heap é uma região compartilhada por todo o processo. Ele existe justamente para dados cujo tempo de vida não se encaixa no ciclo de vida de uma chamada de função. O preço é que alguém precisa descobrir quando aquele dado pode ser liberado, e esse alguém é o garbage collector. Cada objeto no heap é trabalho de marcação e varredura para o GC.

Então a conta é essa: stack é barata na alocação e de graça no GC. Heap é mais cara na alocação e, pior, continua custando depois.

Parte 1: quem decide é o compilador, não você

Aqui está o ponto que reorganiza o entendimento de quem vem de C ou C++: em Go, não existe sintaxe para escolher entre stack e heap. new não significa heap. &T{} não significa heap. Uma variável sem & não significa stack.

A própria FAQ oficial é direta sobre isso:

E o mesmo texto explica o critério:

"se o compilador não conseguir provar que a variável não é referenciada depois que a função retorna, então o compilador precisa alocar a variável no heap garantido pelo coletor de lixo, para evitar erros de ponteiro pendurado."

Repare na formulação: o compilador não procura motivos para mandar algo para o heap. Ele tenta provar que pode manter na stack, e o heap é o que sobra quando a prova falha. É uma diferença importante, e ela explica boa parte do comportamento que parece estranho depois.

O comentário no topo do código-fonte do analisador enuncia as duas regras que sustentam tudo:

"(1) ponteiros para objetos na stack não podem ser guardados no heap e (2) ponteiros para um objeto na stack não podem sobreviver a esse objeto"

— cmd/compile/internal/escape/escape.go

Voltando ao NewCounter: o ponteiro devolvido sobrevive ao frame, logo a regra (2) seria violada se c ficasse na stack. O compilador então move c para o heap. O programa continua correto sem você fazer nada, e é exatamente esse "sem você fazer nada" que o C não oferece.

Uma consequência prática que quase ninguém aproveita: new(T) pode perfeitamente ficar na stack.

package cfg

type Config struct {
    Retries int
    Timeout int
}

//go:noinline
func validate(c *Config) bool { return c.Retries > 0 }

func Load() bool {
    c := new(Config) // "new" não quer dizer heap
    c.Retries = 3
    c.Timeout = 5
    return validate(c)
}

./cfg.go:9:15:  c does not escape
./cfg.go:12:10: new(Config) does not escape

O ponteiro entra em validate, é lido e morre ali. Nada sobrevive ao frame de Load, então a prova passa e o new fica na stack.

Parte 2: enxergando a decisão com -gcflags=-m

Você não precisa adivinhar nada disso. A flag -m pede ao compilador que imprima as decisões de otimização:

go build -gcflags=-m ./...

Vamos a um exemplo com três variações do mesmo cálculo:

package geo

type Point struct {
    X, Y int
}

// 1. valor local, sem ponteiro
func DistanceSquared(x, y int) int {
    p := Point{X: x, Y: y}
    return p.X*p.X + p.Y*p.Y
}

// 2. pega o endereço, mas o ponteiro morre aqui
func DistanceSquaredPtr(x, y int) int {
    p := &Point{X: x, Y: y}
    return p.X*p.X + p.Y*p.Y
}

// 3. o ponteiro sai da função
func NewPoint(x, y int) *Point {
    return &Point{X: x, Y: y}
}

A saída relevante:

./geo.go:15:7: &Point{...} does not escape
./geo.go:21:9: &Point{...} escapes to heap

O caso 1 nem aparece: sem ponteiro, não há o que analisar. O caso 2 mostra a parte contraintuitiva: usar & não manda nada para o heap. O endereço nasce e morre dentro do frame, então a prova passa. Só o caso 3 escapa, porque o endereço atravessa a fronteira da função.

Vale conhecer as três formas de usar a flag:

Lendo o vocabulário da saída

A saída do -m tem um jargão próprio, e ele diz mais do que "escapou ou não". Considere um trecho realista de uma camada de repositório:

package orders

type Order struct {
    ID     int64
    Total  int64
    Status string
}

// só lê o parâmetro
func isPaid(o *Order) bool {
    return o.Status == "paid"
}

// devolve o parâmetro
func FirstPaid(orders []*Order) *Order {
    for _, o := range orders {
        if isPaid(o) {
            return o
        }
    }
    return nil
}

type Registry struct {
    byID map[int64]*Order
}

// guarda o parâmetro em uma estrutura de vida longa
func (r *Registry) Add(o *Order) {
    r.byID[o.ID] = o
}

E a saída:

./orders.go:10:13: o does not escape
./orders.go:15:16: leaking param: orders to result ~r0 level=1
./orders.go:29:7:  r does not escape
./orders.go:29:24: leaking param: o

Traduzindo cada linha:

• does not escape: o compilador provou que o valor não sobrevive à chamada. É a resposta que você quer.
• leaking param: o: o parâmetro vaza sem qualificação, ou seja, vai parar no heap (aqui, dentro do map do Registry). Quem chamar Add vai ter o argumento alocado no heap.
• leaking param: orders to result ~r0 level=1: vazamento condicional. O parâmetro não vai para o heap; ele sai pelo resultado da função. O level=1 é o número de dereferências: o que sai é o conteúdo do slice, não o slice em si. Isso é o que permite ao compilador analisar quem chama sem reanalisar a função inteira.
• moved to heap: x: aparece quando uma variável declarada localmente precisou virar alocação no heap.

Essa distinção entre "vaza para o heap" e "vaza para o resultado" é o coração da parte interprocedural. O compilador resume cada função em parameter tags e usa esse resumo nos pontos de chamada, em vez de reanalisar tudo. Internamente, ele monta um grafo dirigido em que os vértices são variáveis e as arestas são atribuições, com peso igual ao número de dereferências menos o número de operações de endereço (p = &q pesa -1, p = q pesa 0, p = *q pesa 1). Depois procura caminhos que violem as duas regras.

Parte 3: o que realmente faz um valor escapar

Na prática, quase todo escape em código de aplicação cai em um destes cinco padrões.

1. O ponteiro sobrevive ao frame

Já vimos: retornar &local, enviar um ponteiro por channel, guardar em uma variável global. É o caso óbvio, e normalmente é o caso correto: se o dado precisa viver mais que a chamada, ele tem que estar no heap.

O que não é óbvio é que isso interage com o inlining. Se o construtor for inlinado no chamador, a fronteira que causava o escape simplesmente deixa de existir:

package inl

type Point struct{ X, Y int }

func newPoint(x, y int) *Point { return &Point{X: x, Y: y} }

func Norm(x, y int) int {
    p := newPoint(x, y) // inlinado aqui
    return p.X*p.X + p.Y*p.Y
}

./inl.go:8:15: inlining call to newPoint
./inl.go:5:41: &Point{...} escapes to heap     // newPoint analisada sozinha
./inl.go:8:15: &Point{...} does not escape     // depois de inlinar em Norm

A mesma expressão aparece duas vezes com veredictos opostos. Não é inconsistência: o compilador roda a etapa de devirtualização e inlining antes da escape analysis, então o que ele analisa é o código já expandido. Medindo com -benchmem, a diferença é exatamente uma alocação:

BenchmarkInlined-8     1000000000    1.065 ns/op     0 B/op    0 allocs/op
BenchmarkNoInline-8      64799066   18.47  ns/op    16 B/op    1 allocs/op

2. Boxing em interface

Esse é o mais comum em código real e o mais fácil de não perceber, porque ele não tem & nenhum. Uma interface em Go é um par (tipo, ponteiro para o valor). Guardar um valor concreto em uma interface, any incluso, significa que esse valor precisa de um endereço, e é aí que a escape analysis entra: se o compilador não conseguir provar que a interface fica contida na função, o valor empacotado vai para o heap.

O exemplo mais frequente é logging estruturado:

// chaves e valores soltos: cada valor vira um "any"
func logSlowQuery(query string, elapsed time.Duration) {
    logger.Warn("slow query", "query", query, "elapsed", elapsed)
}

// atributos tipados: nada precisa ser empacotado em any
func logSlowQueryAttrs(ctx context.Context, query string, elapsed time.Duration) {
    logger.LogAttrs(ctx, slog.LevelWarn, "slow query",
        slog.String("query", query),
        slog.Duration("elapsed", elapsed),
    )
}

Com -m, a primeira versão acusa elapsed escapes to heap. E com um handler escrevendo em io.Discard, para isolar o custo de formatação:

BenchmarkLogAny-8     1000000    1028   ns/op    24 B/op    1 allocs/op
BenchmarkLogAttrs-8   1314451     911.5 ns/op     0 B/op    0 allocs/op

Os 24 bytes se decompõem assim: Logger.Warn recebe ...any, então tanto query quanto elapsed precisam ser empacotados. Empacotar a string custa 16 bytes (o cabeçalho da string precisa de um endereço) e empacotar o time.Duration custa mais 8. Já slog.String e slog.Duration devolvem um slog.Attr, que guarda esses dados em campos próprios da struct, sem passar por any. Zero alocações. É exatamente para isso que a API LogAttrs existe.

O mesmo vale para fmt.Sprintf. Um caso concreto: montar uma chave de cache num caminho quente.

func cacheKeySprintf(tenantID, userID int64) string {
    return fmt.Sprintf("user:%d:%d", tenantID, userID)
}

func cacheKeyAppend(tenantID, userID int64) string {
    buf := make([]byte, 0, 32)
    buf = append(buf, "user:"...)
    buf = strconv.AppendInt(buf, tenantID, 10)
    buf = append(buf, ':')
    buf = strconv.AppendInt(buf, userID, 10)
    return string(buf)
}

BenchmarkSprintf-8   10583786   124.7 ns/op    24 B/op    2 allocs/op
BenchmarkAppend-8    35509032    47.95 ns/op   16 B/op    1 allocs/op

O -m acusa tenantID escapes to heap e userID escapes to heap na primeira versão, por causa do ...any. Um profile de memória mostra de onde vêm os 24 bytes: 16 no string(p.buf) interno do fmt.Sprintf e 8 no empacotamento do userID. O tenantID é a constante 42 e não custa nada, pelo mesmo motivo da observação acima.

Na segunda versão, o -m diz make([]byte, 0, 32) does not escape e append does not escape. O buffer inteiro vive na stack, e só o string(buf) final aloca, porque strings em Go são imutáveis e o resultado precisa sobreviver à função.

3. Guardar um ponteiro em algo que já está no heap

Esta é a regra (1) em ação, e ela é transitiva. Se você escreve um ponteiro dentro de um slice, map, struct ou closure que está no heap, o alvo tem que ir junto. Não existe ponteiro do heap para a stack.

É por isso que o Registry.Add do exemplo anterior marca leaking param: o sem qualificação: o map sobrevive à chamada, então tudo que entra nele sobrevive também.

Uma consequência que vale internalizar: a decisão se propaga para trás. Uma única linha que guarda um ponteiro em uma estrutura de vida longa faz o valor original escapar, mesmo que ele tenha sido criado dez frames acima.

4. Closures e goroutines

Uma closure captura variáveis. Se a closure escapa, as variáveis capturadas por referência escapam junto.

package jobs

import "sync"

type Job struct {
    ID      int
    Payload string
}

func ProcessAsync(jobs []Job) int {
    var mu sync.Mutex
    var wg sync.WaitGroup
    total := 0
    for _, j := range jobs {
        wg.Add(1)
        go func() {
            defer wg.Done()
            mu.Lock()
            total += len(j.Payload)
            mu.Unlock()
        }()
    }
    wg.Wait()
    return total
}

./jobs.go:10:19: leaking param content: jobs
./jobs.go:11:6:  moved to heap: mu
./jobs.go:12:6:  moved to heap: wg
./jobs.go:13:2:  moved to heap: total
./jobs.go:16:6:  func literal escapes to heap

Toda goroutine tem sua própria stack, então uma variável compartilhada entre a goroutine pai e a filha não pode viver na stack de nenhuma das duas. mu, wg e total vão para o heap porque a closure as modifica e precisa do endereço.

Repare no que não está na lista: j. Como j só é lido, o compilador a captura por cópia, guardando o valor direto dentro do objeto da closure em vez de criar uma variável separada no heap. É um detalhe pequeno, mas mostra que "capturou" e "escapou" não são a mesma coisa.

5. Tamanho: grande demais para a stack

Independentemente do tempo de vida, existe um teto. Se o valor for maior que o limite, ele vai para o heap, e o -m=2 diz o motivo com todas as letras: too large for stack.

No Go 1.26 os limites são:

//go:noinline
func checksum(b []byte) int {
    t := 0
    for _, v := range b {
        t += int(v)
    }
    return t
}

func small() int {
    var buf [64 * 1024]byte // 64 KiB: fica na stack
    return checksum(buf[:])
}

func big() int {
    var buf [129 * 1024]byte // 129 KiB: moved to heap
    return checksum(buf[:])
}

Existe ainda um caso à parte: make([]T, n) com n não constante. Aqui o compilador não sabe o tamanho em tempo de compilação, então, desde o Go 1.25, ele gera as duas versões e escolhe em tempo de execução, reservando uma pequena área fixa na stack (32 bytes por padrão) e caindo para o heap quando não couber:

BenchmarkVarMakeSmall-8   160536319    7.452 ns/op     0 B/op    0 allocs/op   // n = 16
BenchmarkVarMakeLarge-8    19328575   63.39  ns/op    64 B/op    1 allocs/op   // n = 64

Os dois benchmarks rodam a mesma linha de código, make([]byte, n), com valores diferentes de n. É provavelmente o exemplo mais literal de que "essa linha aloca?" não é uma pergunta bem formada em Go.

Parte 4: medindo, não adivinhando

Chegando aqui, a tentação é sair rodando -gcflags=-m no projeto inteiro. Não faça isso: um serviço médio produz milhares de linhas de saída, a maioria irrelevante. Escape analysis é uma ferramenta de diagnóstico, não de auditoria.

O fluxo que funciona é o inverso, e começa pela alocação, não pelo escape:

1. Meça alocações onde importa. -benchmem mostra allocs/op, que é o número que se traduz direto em pressão de GC:

go test -run='^$' -bench=. -benchmem ./...

2. Descubra quem aloca. Um profile de memória aponta as linhas responsáveis:

go test -run='^$' -bench=BenchmarkSprintf -memprofile=mem.out ./key/
go tool pprof -top -sample_index=alloc_objects key.test mem.out

      flat  flat%   sum%        cum   cum%
  10780836 67.00% 67.00%   10780836 67.00%  fmt.Sprintf
   5308497 32.99%   100%   16089333   100%  key.cacheKeySprintf (inline)

Use alloc_objects (quantidade) e alloc_space (bytes) para investigar pressão de GC. O default do pprof é inuse_space, que responde outra pergunta: o que ainda está vivo agora.

3. Só então use -gcflags=-m, no pacote que o profile apontou, para entender por que aquela linha específica aloca.

Nessa ordem, você gasta esforço só onde tem retorno. Na ordem inversa, você reescreve código legível para eliminar alocações que aconteciam três vezes por requisição.

Limitações, exceções e armadilhas

Esta é a parte que separa entender o mecanismo de usá-lo bem.

A análise é conservadora, e isso é assimétrico. does not escape é uma prova: pode confiar. escapes to heap é a ausência de prova, e pode perfeitamente ser um falso positivo. O caso mais comum é a chamada indireta:

package metrics

type Metric struct {
    Name  string
    Value float64
}

func report(m *Metric) { _ = m.Value }

func DirectCall() {
    m := &Metric{Name: "latency", Value: 1.5}
    report(m) // chamada estática
}

func IndirectCall(fn func(*Metric)) {
    m := &Metric{Name: "latency", Value: 1.5}
    fn(m) // chamada indireta
}

./metrics.go:11:7: &Metric{...} does not escape
./metrics.go:16:7: &Metric{...} escapes to heap

Corpos idênticos, resultados opostos. Em IndirectCall, o compilador não sabe qual função fn é, então não tem parameter tag para consultar e assume o pior. O mesmo acontece com chamadas de método por interface que a devirtualização não consegue resolver, e com reflect.

A saída do -m não é uma API estável. Ela é uma ferramenta de diagnóstico do compilador; o formato e o conteúdo mudam entre versões. Não construa testes ou CI em cima dela.

Stack também não é de graça. Frames grandes empurram a goroutine para perto do limite da stack, e crescer a stack significa alocar uma área maior e copiar a stack inteira, corrigindo os ponteiros internos. Trocar uma alocação de heap por um array de 100 KiB na stack de uma função recursiva pode piorar as coisas.

0 allocs/op não é sinônimo de rápido. É um proxy para pressão de GC, que é uma das componentes do custo. Se ns/op não melhorou, a mudança não valeu.

Não escreva código estranho para agradar o analisador. Isso é o mais importante da seção. Padrões como quebrar funções para forçar inlining, evitar interfaces em código frio ou substituir fmt.Sprintf por concatenação manual em um endpoint chamado dez vezes por dia trocam legibilidade por nada. O critério continua sendo o profile.

sync.Pool não é um substituto. Ele reduz a taxa de alocação reaproveitando objetos, mas não os tira do heap: a documentação diz explicitamente que "qualquer item guardado no Pool pode ser removido automaticamente a qualquer momento", e na prática o GC vai limpando o pool a cada ciclo (com um victim cache que dá a cada objeto um ciclo extra de sobrevida). É uma ferramenta para objetos caros e comprovadamente quentes, com o risco adicional de reter memória e de vazar dados entre usos se você esquecer de resetar o objeto.

unsafe.Pointer e stack allocation não se dão bem. Como o compilador move valores entre stack e heap e o runtime copia stacks, código que faz aritmética de ponteiro fora das regras documentadas em unsafe.Pointer pode quebrar quando uma alocação muda de lugar. As notas do Go 1.25 citam isso explicitamente ao introduzir mais alocações de slice na stack.

Mudanças entre versões

Os limites e otimizações citados aqui não são estáveis ao longo do tempo. As mudanças recentes que afetam este assunto:

Vale destacar o último ponto. Green Tea não altera nenhuma decisão de escape analysis; ele reduz o custo de manter dados no heap, que é a parte do overhead que sobra depois da alocação. Isso empurra ainda mais a régua na direção de "meça antes de otimizar": uma micro-otimização que valia a pena em um projeto de dois anos atrás pode não valer mais, e a única forma de saber é medir na versão que você está usando.

Juntando tudo: o caminho mental

Se eu tivesse que resumir o raciocínio em uma sequência de perguntas:

1. Esse código está em um caminho quente? Se não está, pare aqui. Escape analysis é assunto para o 1% do código que o profile aponta.
2. Quantas alocações por operação? -benchmem primeiro, pprof com alloc_objects depois. Só então -gcflags=-m, e só no pacote suspeito.
3. A alocação é necessária ou acidental? Se o dado precisa sobreviver à chamada, ela é necessária e você está no lugar errado. Acidentais são quase sempre boxing em any, closures em goroutines ou um ponteiro entrando em uma estrutura de vida longa.
4. Existe uma API que evita o boxing? slog.LogAttrs em vez de chaves soltas, strconv.Append* em vez de fmt.Sprintf, um buffer local em vez de um io.Writer genérico.
5. A mudança melhorou ns/op, e não só allocs/op? Se não melhorou, reverta e mantenha a versão legível.

O que eu levaria deste artigo, no fim, é uma inversão de perspectiva. Escape analysis não é uma otimização que você aplica; é uma garantia de correção que o compilador te dá de graça, e que por acaso também é rápida na maior parte das vezes. Retornar &local em Go é seguro pelo mesmo motivo pelo qual é eficiente: o compilador entende o tempo de vida dos seus dados melhor do que a sintaxe do seu código consegue expressar. Da mesma forma que os zero values tiraram de você a obrigação de lembrar de inicializar, o escape analysis tira a obrigação de decidir onde as coisas moram. Nos dois casos, o ganho é o mesmo: menos decisões para errar.

Referências

• Go FAQ — How do I know whether a variable is allocated on the heap or the stack? — a posição oficial sobre o assunto, e o critério que o compilador usa.
• cmd/compile/internal/escape/escape.go — o comentário no topo do arquivo descreve as duas invariantes, o grafo de fluxo de dados e as parameter tags.
• cmd/compile/internal/ir/cfg.go — os limites MaxStackVarSize (128 KiB) e MaxImplicitStackVarSize (64 KiB).
• cmd/compile/internal/gc/main.go — a ordem das etapas do compilador; devirtualização e inlining rodam antes da escape analysis.
• runtime/stack.go — stackMin, o tamanho inicial de 2 KiB das stacks de goroutine e o mecanismo de crescimento por cópia.
• runtime/iface.go — convT64 e o array staticuint64s, que evita a alocação ao empacotar inteiros menores que 256 em uma interface.
• cfg.go na tag go1.23.0 e na tag go1.24.0 — a comparação que mostra MaxStackVarSize indo de 10 MB para 128 KiB.
• Go 1.25 Release Notes — Compiler — alocação na stack do backing store de slices em mais situações, e a flag variablemakehash.
• Go 1.26 Release Notes — Green Tea GC — o novo coletor como padrão e o impacto esperado no overhead de GC.
• go help build — a sintaxe pattern= do -gcflags e por que all=-m é diferente de -m.
• log/slog — Performance considerations — a recomendação oficial de Logger.LogAttrs para evitar alocações, e outras dicas de custo em logging.
• Documentação do unsafe.Pointer — os padrões válidos de conversão, e por que sair deles quebra na presença de stack copying.
• Profiling Go Programs — o fluxo de trabalho com pprof no blog oficial.