golang.org/x/sync v0.21.0: errgroup.Group

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify golang.org/x/sync/errgroup.Group in pkg:golang/golang.org/x/sync@v0.21.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/sync@v0.21.0
Demonstrate these symbols/APIs:
  - golang.org/x/sync/errgroup.Group

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:66d125f6761ed1000d0374e54da760f3c0519e1a8dffa4e7b7077a089468b2ac","contract":["errgroup.Group executes concurrent tasks via Go and Wait blocks until all subtasks complete","errgroup.Group Wait captures and returns the first non-nil error returned by a subtask","errgroup.WithContext derives a context canceled on the first subtask error or Wait return","errgroup.Group SetLimit restricts the maximum number of concurrent active goroutines","errgroup.Group TryGo launches a goroutine if capacity is available and reports false when at limit"],"goal":"verify golang.org/x/sync/errgroup.Group in pkg:golang/golang.org/x/sync@v0.21.0","kind":"HOW","packages":["pkg:golang/golang.org/x/sync@v0.21.0"],"schemaVersion":1,"symbols":["golang.org/x/sync/errgroup.Group"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/golang.org/x/sync@v0.21.0"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/sync@v0.21.0","symbols":["golang.org/x/sync/errgroup.Group"],"verifierAdapter":"golang@1"}

module sample

go 1.25.0

require golang.org/x/sync v0.21.0

golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=

package sample

import (
	"context"
	"sync/atomic"

	"golang.org/x/sync/errgroup"
)

// TaskFunc defines a unit of work returning an error on failure.
type TaskFunc func() error

// ParallelRunner coordinates concurrent execution of tasks with an optional limit.
type ParallelRunner struct {
	limit int
}

// NewParallelRunner creates a ParallelRunner with the specified concurrency limit.
// A limit <= 0 indicates unlimited concurrency.
func NewParallelRunner(limit int) *ParallelRunner {
	return &ParallelRunner{limit: limit}
}

// ExecuteTasks runs all supplied tasks concurrently and returns the count of completed tasks and the first error encountered.
func (r *ParallelRunner) ExecuteTasks(ctx context.Context, tasks []TaskFunc) (int64, error) {
	g, gCtx := errgroup.WithContext(ctx)
	if r.limit > 0 {
		g.SetLimit(r.limit)
	}

	var completed int64
	for _, task := range tasks {
		t := task
		g.Go(func() error {
			select {
			case <-gCtx.Done():
				return gCtx.Err()
			default:
			}

			if err := t(); err != nil {
				return err
			}
			atomic.AddInt64(&completed, 1)
			return nil
		})
	}

	err := g.Wait()
	return atomic.LoadInt64(&completed), err
}

{
  "schemaVersion": 1,
  "goal": "verify golang.org/x/sync/errgroup.Group in pkg:golang/golang.org/x/sync@v0.21.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/sync@v0.21.0"
  ],
  "symbols": [
    "golang.org/x/sync/errgroup.Group"
  ]
}

package main

import (
	"context"
	"errors"
	"fmt"
	"os"
	"sync/atomic"
	"time"

	"golang.org/x/sync/errgroup"
	"sample"
)

func main() {
	// Assertion 1: errgroup.Group executes concurrent tasks via Go and Wait blocks until all subtasks complete
	{
		var g errgroup.Group
		var count int64
		numTasks := 10
		for i := 0; i < numTasks; i++ {
			g.Go(func() error {
				time.Sleep(5 * time.Millisecond)
				atomic.AddInt64(&count, 1)
				return nil
			})
		}
		if err := g.Wait(); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL assertion 1: unexpected error from Wait: %v\n", err)
			os.Exit(1)
		}
		if got := atomic.LoadInt64(&count); got != int64(numTasks) {
			fmt.Fprintf(os.Stderr, "FAIL assertion 1: expected %d completed tasks, got %d\n", numTasks, got)
			os.Exit(1)
		}
	}

	// Assertion 2: errgroup.Group Wait captures and returns the first non-nil error returned by a subtask
	{
		var g errgroup.Group
		errExpected := errors.New("primary failure")
		g.Go(func() error {
			time.Sleep(5 * time.Millisecond)
			return errExpected
		})
		g.Go(func() error {
			time.Sleep(25 * time.Millisecond)
			return errors.New("secondary failure")
		})
		g.Go(func() error {
			time.Sleep(10 * time.Millisecond)
			return nil
		})
		err := g.Wait()
		if err == nil {
			fmt.Fprintf(os.Stderr, "FAIL assertion 2: expected error from Wait, got nil\n")
			os.Exit(1)
		}
		if !errors.Is(err, errExpected) && err.Error() != errExpected.Error() {
			fmt.Fprintf(os.Stderr, "FAIL assertion 2: expected %v, got %v\n", errExpected, err)
			os.Exit(1)
		}
	}

	// Assertion 3: errgroup.WithContext derives a context canceled on the first subtask error or Wait return
	{
		g, ctx := errgroup.WithContext(context.Background())
		errFail := errors.New("trigger cancel")
		g.Go(func() error {
			time.Sleep(5 * time.Millisecond)
			return errFail
		})
		canceledDetected := make(chan struct{})
		g.Go(func() error {
			select {
			case <-ctx.Done():
				close(canceledDetected)
				return ctx.Err()
			case <-time.After(2 * time.Second):
				return errors.New("timeout waiting for context cancellation")
			}
		})
		select {
		case <-canceledDetected:
			// Verified: context was canceled promptly
		case <-time.After(1 * time.Second):
			fmt.Fprintf(os.Stderr, "FAIL assertion 3: context was not canceled when task failed\n")
			os.Exit(1)
		}
		if err := g.Wait(); err == nil {
			fmt.Fprintf(os.Stderr, "FAIL assertion 3: expected non-nil error from Wait\n")
			os.Exit(1)
		}
	}

	// Assertion 4: errgroup.Group SetLimit restricts the maximum number of concurrent active goroutines
	{
		var g errgroup.Group
		limit := 2
		g.SetLimit(limit)
		var currentActive int64
		var maxObserved int64
		numTasks := 10
		for i := 0; i < numTasks; i++ {
			g.Go(func() error {
				curr := atomic.AddInt64(&currentActive, 1)
				for {
					oldMax := atomic.LoadInt64(&maxObserved)
					if curr <= oldMax || atomic.CompareAndSwapInt64(&maxObserved, oldMax, curr) {
						break
					}
				}
				time.Sleep(10 * time.Millisecond)
				atomic.AddInt64(&currentActive, -1)
				return nil
			})
		}
		if err := g.Wait(); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL assertion 4: unexpected error: %v\n", err)
			os.Exit(1)
		}
		if max := atomic.LoadInt64(&maxObserved); max > int64(limit) {
			fmt.Fprintf(os.Stderr, "FAIL assertion 4: max concurrency %d exceeded limit %d\n", max, limit)
			os.Exit(1)
		}
	}

	// Assertion 5: errgroup.Group TryGo launches a goroutine if capacity is available and reports false when at limit
	{
		var g errgroup.Group
		g.SetLimit(1)
		blockerStarted := make(chan struct{})
		releaseBlocker := make(chan struct{})

		startedFirst := g.TryGo(func() error {
			close(blockerStarted)
			<-releaseBlocker
			return nil
		})
		if !startedFirst {
			fmt.Fprintf(os.Stderr, "FAIL assertion 5: expected first TryGo to return true\n")
			os.Exit(1)
		}

		<-blockerStarted
		// Reached capacity: 1 of 1 active goroutine
		startedSecond := g.TryGo(func() error {
			return nil
		})
		if startedSecond {
			fmt.Fprintf(os.Stderr, "FAIL assertion 5: expected second TryGo to return false when at limit\n")
			os.Exit(1)
		}

		close(releaseBlocker)
		if err := g.Wait(); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL assertion 5: unexpected error from Wait: %v\n", err)
			os.Exit(1)
		}

		// Capacity freed: TryGo should now succeed
		startedThird := g.TryGo(func() error {
			return nil
		})
		if !startedThird {
			fmt.Fprintf(os.Stderr, "FAIL assertion 5: expected TryGo to return true after previous completed\n")
			os.Exit(1)
		}
		if err := g.Wait(); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL assertion 5: unexpected error from Wait: %v\n", err)
			os.Exit(1)
		}
	}

	// Runner integration check
	{
		runner := sample.NewParallelRunner(2)
		completed, err := runner.ExecuteTasks(context.Background(), []sample.TaskFunc{
			func() error { return nil },
			func() error { return nil },
			func() error { return nil },
		})
		if err != nil || completed != 3 {
			fmt.Fprintf(os.Stderr, "FAIL runner: completed %d, err %v\n", completed, err)
			os.Exit(1)
		}
	}

	fmt.Println("All contract assertions passed successfully.")
	os.Exit(0)
}