Extensiones de errgroup y golang.org/x/sync

Goroutines coordinadas con cancelación por primer error.

Resumen

golang.org/x/sync/errgroup agrupa goroutines que comparten un destino: un fallo cancela el resto y presenta un único error desde Wait.

Paquetes relacionados en x/sync añaden paralelismo limitado (SetLimit), deduplicación (singleflight) y semáforos contadores (semaphore).

Estas extensiones llenan vacíos en el paquete sync de la biblioteca estándar para la orquestación de servicios.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

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
}

Cuándo usar esto:

• Fetchings HTTP o gRPC paralelos que deben abortar juntos ante un fallo.
• Trabajos por lotes con un límite de concurrencia (SetLimit).
• Prevención de estampida de caché con singleflight.Group.
• Servicios de larga duración que limitan tareas en segundo plano con semaphore.Weighted.

Ejemplo Funcional

// 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")
    }
}

Lo que esto demuestra:

• WithContext vincula la vida útil de las goroutines a la cancelación compartida.
• SetLimit(2) evita que se realicen más de dos fetchings a la vez.
• singleflight ejecuta un cargador por clave mientras los que esperan comparten el resultado.
• semaphore.Weighted bloquea de forma consciente del contexto, a diferencia de los trucos de canales puros.

Inmersión Profunda

Cómo Funciona

• errgroup.Group incrusta un WaitGroup más una ranura de error protegida por un mutex.
• El primer error no nulo de Go activa cancel en el contexto derivado de WithContext.
• SetLimit(n) utiliza un semáforo de canal interno; n < 1 significa ilimitado.
• singleflight.Do agrupa llamadas concurrentes con la misma clave hasta que la función líder retorna.

Mapa del Paquete x/sync

Notas de Go

// errgroup sin cancel - usar cuando los fallos no deben detener a los hermanos
var g errgroup.Group
g.Go(func() error { return maybeFail() })
_ = g.Wait()

• Usa errgroup.Group simple cuando el éxito parcial es aceptable y fusionas los errores tú mismo.
• Siempre pasa el ctx derivado de WithContext a las I/O, no al padre.

Trampas

• Usar el ctx padre dentro de Go después de que un hermano haya fallado - El trabajo continúa después de la cancelación. Solución: Usa solo el ctx derivado.
• Llamar a Go después de Wait - Comportamiento indefinido; crea un nuevo Grupo por lote. Solución: Un grupo por operación lógica.
• SetLimit sin respetar ctx en tareas largas - Las ranuras permanecen ocupadas hasta que la tarea finaliza. Solución: Honra ctx.Done() en los cuerpos de fetch.
• singleflight olvidando el error compartido - Los que esperan reciben el mismo error, lo cual es lo habitual. Solución: No usar para claves no relacionadas en un mismo Grupo.
• Panic dentro de Go - Causa el cierre del proceso; errgroup no recupera. Solución: Evita los panics; usa envoltorios seguros en producción.
• Reemplazar WaitGroup en todas partes - Exagerado cuando no se necesita cancelación compartida. Solución: sync.WaitGroup para uniones simples.

Alternativas

Preguntas Frecuentes

Relacionados

• Conceptos Básicos de Concurrencia Avanzada - ejemplo introductorio de errgroup
• Fan-In, Fan-Out y Etapas de Pipeline - errgroup en pipelines
• Pools de Workers y Colas de Tareas - SetLimit vs pools
• Limitación de Tasa y Backpressure - semaphore.Weighted
• Propagación de Cancelación en Manejadores HTTP - ctx del manejador

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación) y golangci-lint (última - verificar conjunto de linters en la compilación).