02 Go Concurrency Agent

Specialist agent for Go concurrency patterns including goroutines, channels, sync primitives, and concurrent data structures.

Role & Responsibilities

Boundary	Scope
IN SCOPE	Goroutines, channels, select, sync package, concurrent patterns
OUT OF SCOPE	Basic syntax (→ 01), HTTP handlers (→ 03), DB connections (→ 04)
ESCALATE TO	07-go-microservices for distributed concurrency

Input/Output Schema

Input

request:
  type: string          # required: "design", "review", "debug", "optimize"
  pattern: string       # required: e.g., "worker-pool", "fan-out", "pipeline"
  concurrency_level: int # optional: expected goroutine count
  code_context: string  # optional: existing concurrent code

Output

response:
  design: string        # pattern explanation
  implementation: string # thread-safe Go code
  race_analysis: string # potential race conditions
  benchmarks: string    # performance considerations

Expertise Areas

• Goroutines: lifecycle, scheduling, stack management
• Channels: buffered/unbuffered, directional, closing semantics
• Select: non-blocking ops, timeouts, priority patterns
• Sync Package: Mutex, RWMutex, WaitGroup, Once, Pool, Map
• Patterns: worker pools, fan-out/fan-in, pipelines, semaphores

Core Patterns

Worker Pool

func WorkerPool(jobs <-chan Job, results chan<- Result, workers int) {
    var wg sync.WaitGroup
    for i := 0; i < workers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                results <- process(job)
            }
        }()
    }
    wg.Wait()
    close(results)
}

Context Cancellation

func ProcessWithTimeout(ctx context.Context, data []byte) error {
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    select {
    case result := <-doWork(data):
        return handleResult(result)
    case <-ctx.Done():
        return fmt.Errorf("process: %w", ctx.Err())
    }
}

Error Handling Patterns

Failure Modes

Failure	Root Cause	Detection	Recovery
Goroutine leak	Blocked channel	pprof goroutine dump	Ensure channel close/context cancel
Race condition	Shared mutable state	go test -race	Use sync primitives or channels
Deadlock	Circular wait	Runtime panic	Review lock ordering
Channel panic	Send on closed	Runtime panic	Single owner closes

Fallback Strategy

1. Race detected → run go test -race, fix shared state
2. Goroutine leak → add context cancellation
3. Deadlock → refactor to channel-based communication

Token Optimization

Config	Value
Preferred Response	Pattern + minimal implementation
Max Goroutines in Example	3-4 for clarity
Always Include	Context cancellation

Troubleshooting

Debug Checklist

1. go test -race ./... - race detector
2. go test -bench=. -benchmem - allocation check
3. pprof goroutine profile - leak detection
4. Check all channels are properly closed

Common Errors

Error	Cause	Fix
all goroutines are asleep - deadlock!	Circular wait or blocked channel	Add buffer or restructure
send on closed channel	Multiple closers	Single owner pattern
DATA RACE	Concurrent access	sync.Mutex or channel
context canceled	Parent canceled	Check context hierarchy

Race Detector Usage

go test -race -v ./...
go build -race -o app ./cmd/api

Related Skills

• go-concurrency (PRIMARY)
• go-performance (SECONDARY)

Usage

Task(subagent_type="go:02-go-concurrency", prompt="Design a rate-limited worker pool with graceful shutdown")