Extensões errgroup & golang.org/x/sync

Goroutines coordenadas com cancelamento no primeiro erro.

Resumo

golang.org/x/sync/errgroup agrupa goroutines que compartilham o mesmo destino: uma falha cancela as demais e apresenta um único erro de Wait.

Pacotes relacionados em x/sync adicionam paralelismo limitado (SetLimit), deduplicação (singleflight) e semáforos de contagem (semaphore).

Essas extensões preenchem lacunas no pacote sync da biblioteca padrão para orquestração estilo serviço.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

g, ctx := errgroup.WithContext(ctx)
g.SetLimit(4)
g.Go(func() error { return stepA(ctx) })
g.Go(func() error { return stepB(ctx) })
if err := g.Wait(); err != nil {
    return err
}

Quando usar isso:

• Buscas paralelas de HTTP ou gRPC que devem abortar juntas em caso de falha.
• Tarefas em lote com um teto de concorrência (SetLimit).
• Prevenção de cache stampede com singleflight.Group.
• Serviços de longa duração que limitam tarefas em segundo plano com semaphore.Weighted.

Exemplo de Trabalho

// go.mod: module example.com/errgroupdemo
package main
 
import (
    "context"
    "fmt"
    "sync"
    "time"
 
    "golang.org/x/sync/errgroup"
    "golang.org/x/sync/semaphore"
    "golang.org/x/sync/singleflight"
)
 
func fetch(ctx context.Context, name string, delay time.Duration, fail bool) error {
    select {
    case <-ctx.Done():
        return ctx.Err()
    case <-time.After(delay):
        if fail {
            return fmt.Errorf("%s failed", name)
        }
        fmt.Println("fetched", name)
        return nil
    }
}
 
func parallelFetch(ctx context.Context) error {
    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(2)
    tasks := []struct {
        name string
        d    time.Duration
        fail bool
    }{
        {"users", 20 * time.Millisecond, false},
        {"orders", 30 * time.Millisecond, false},
        {"inventory", 10 * time.Millisecond, true},
    }
    for _, t := range tasks {
        t := t
        g.Go(func() error {
            return fetch(ctx, t.name, t.d, t.fail)
        })
    }
    return g.Wait()
}
 
func dedupeLoad(g *singleflight.Group, key string) (string, error) {
    v, err, _ := g.Do(key, func() (any, error) {
        time.Sleep(50 * time.Millisecond)
        return "data-for-" + key, nil
    })
    if err != nil {
        return "", err
    }
    return v.(string), nil
}
 
func main() {
    ctx := context.Background()
    if err := parallelFetch(ctx); err != nil {
        fmt.Println("parallel:", err)
    }
 
    var sf singleflight.Group
    var wg sync.WaitGroup
    for i := 0; i < 3; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            s, _ := dedupeLoad(&sf, "account:42")
            fmt.Println(s)
        }()
    }
    wg.Wait()
 
    sem := semaphore.NewWeighted(1)
    if err := sem.Acquire(ctx, 1); err == nil {
        defer sem.Release(1)
        fmt.Println("critical section")
    }
}

O que isso demonstra:

• WithContext vincula a vida útil da goroutine ao cancelamento compartilhado.
• SetLimit(2) impede mais de duas buscas simultaneamente.
• singleflight executa um carregador por chave enquanto os esperadores compartilham o resultado.
• semaphore.Weighted bloqueia com reconhecimento de contexto, ao contrário de truques de canal brutos.

Mergulho Profundo

Como Funciona

• errgroup.Group incorpora um WaitGroup mais um slot de erro protegido por mutex.
• O primeiro erro não nulo de Go aciona cancel no contexto derivado de WithContext.
• SetLimit(n) usa um semáforo de canal interno; n < 1 significa ilimitado.
• singleflight.Do coalesça chamadas concorrentes com a mesma chave até que a função líder retorne.

Mapa do Pacote x/sync

Notas Go

// errgroup sem cancelamento - use quando falhas não devem parar irmãos
var g errgroup.Group
g.Go(func() error { return maybeFail() })
_ = g.Wait()

• Use errgroup.Group simples quando o sucesso parcial for aceitável e você mesclar os erros sozinho.
• Sempre passe o ctx derivado de WithContext para I/O, não o pai.

Armadilhas

• Usando ctx pai dentro de Go após falha de um irmão - O trabalho continua após o cancelamento. Correção: Use apenas o ctx derivado.
• Chamando Go após Wait - Comportamento indefinido; crie um novo Grupo por lote. Correção: Um grupo por operação lógica.
• SetLimit sem respeitar ctx em tarefas longas - Slots permanecem ocupados até o fim da tarefa. Correção: Honre ctx.Done() nos corpos de busca.
• singleflight esquecendo erro compartilhado - Os esperadores recebem o mesmo erro - geralmente desejado. Correção: Não use para chaves não relacionadas em um único Grupo.
• Pânico dentro de Go - Trava o processo; errgroup não recupera. Correção: Mantenha os pânicos fora; use wrappers seguros em produção.
• Substituindo WaitGroup em todos os lugares - Exagero quando nenhum cancelamento compartilhado é necessário. Correção: sync.WaitGroup para junção simples.

Alternativas

FAQs

Relacionados

• Noções Básicas de Concorrência Avançada - Exemplo introdutório de errgroup
• Fan-In, Fan-Out e Estágios de Pipeline - errgroup em pipelines
• Pools de Workers e Filas de Tarefas - SetLimit vs pools
• Limitação de Taxa e Backpressure - semaphore.Weighted
• Propagação de Cancelamento em Manipuladores HTTP - ctx do manipulador

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).