Context

type Context interface {
    Deadline() (deadline time.Time, ok bool)
    Done() <-chan struct{}
    Err() error
    Value(key any) any
}

package main

import (
	"context"
	"errors"
	"fmt"
)

func main() {
	bg := context.Background()
	todo := context.TODO()
	fmt.Println(bg, todo)
	fmt.Println(bg.Err(), bg.Done() == nil)
	_, hasDeadline := bg.Deadline()
	fmt.Println("deadline:", hasDeadline)

	ctx, cancel := context.WithCancel(bg)
	fmt.Println(ctx)
	fmt.Println("before cancel:", ctx.Err())
	cancel()
	<-ctx.Done()
	fmt.Println("after cancel: ", ctx.Err())
	fmt.Println(errors.Is(ctx.Err(), context.Canceled))
	fmt.Printf("%v | %v\n", context.Canceled, context.DeadlineExceeded)

	var te interface{ Timeout() bool }
	fmt.Println(errors.As(context.DeadlineExceeded, &te) && te.Timeout())
	fmt.Println(errors.As(context.Canceled, &te))
}

context.Background context.TODO
<nil> true
deadline: false
context.Background.WithCancel
before cancel: <nil>
after cancel:  context canceled
true
context canceled | context deadline exceeded
true
false

package main

import (
	"context"
	"fmt"
	"sync"
)

// watch blocks until ctx is cancelled and then reports it.
func watch(name string, ctx context.Context, wg *sync.WaitGroup, out chan<- string) {
	defer wg.Done()
	<-ctx.Done()
	out <- fmt.Sprintf("%s: %v", name, ctx.Err())
}

func main() {
	root := context.Background()
	catalogCtx, cancelCatalog := context.WithCancel(root)
	defer cancelCatalog()
	importCtx, cancelImport := context.WithCancel(catalogCtx)
	defer cancelImport()
	pageCtx, cancelPage := context.WithCancel(importCtx)
	defer cancelPage()
	otherCtx, cancelOther := context.WithCancel(root)
	defer cancelOther()

	var wg sync.WaitGroup
	out := make(chan string, 4)
	wg.Add(2)
	go watch("import", importCtx, &wg, out)
	go watch("page", pageCtx, &wg, out)

	cancelCatalog() // cancels catalog, import and page, but not other
	wg.Wait()
	close(out)
	got := map[string]bool{}
	for s := range out {
		got[s] = true
	}
	fmt.Println(got["import: context canceled"], got["page: context canceled"])
	fmt.Println("catalog:", catalogCtx.Err())
	fmt.Println("other:  ", otherCtx.Err())

	// Cancelling a child never affects its parent.
	parent, cancelParent := context.WithCancel(root)
	defer cancelParent()
	child, cancelChild := context.WithCancel(parent)
	cancelChild()
	fmt.Println("child:", child.Err(), "| parent:", parent.Err())
}

true true
catalog: context canceled
other:   <nil>
child: context canceled | parent: <nil>

package main

import (
	"context"
	"fmt"
	"time"
)

func lookup(ctx context.Context, fast bool) error {
	ctx, cancel := context.WithTimeout(ctx, time.Second)
	if fast {
		cancel()
		return nil
	}
	fmt.Println("looking up", ctx.Err())
	return nil
}

func main() {
	fmt.Println(lookup(context.Background(), false))
}

lostcancel/main.go:10:2: the cancel function is not used on all paths (possible context leak)
lostcancel/main.go:16:2: this return statement may be reached without using the cancel var defined on line 10

package main

import (
	"context"
	"fmt"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	fmt.Println(ctx.Err())
}

# example.com/shelf/unusedcancel
unusedcancel/main.go:9:7: declared and not used: cancel

package main

import (
	"context"
	"errors"
	"fmt"
	"time"
)

var errSlowStore = errors.New("store did not answer within the budget")

func main() {
	parent, cancel := context.WithTimeout(context.Background(), time.Hour)
	defer cancel()

	// A child can only shorten, never extend, the parent's deadline.
	short, cancelShort := context.WithTimeout(parent, 50*time.Millisecond)
	defer cancelShort()
	long, cancelLong := context.WithTimeout(short, time.Hour)
	defer cancelLong()

	d1, _ := parent.Deadline()
	d2, _ := short.Deadline()
	d3, _ := long.Deadline()
	fmt.Println("short earlier than parent:", d2.Before(d1))
	fmt.Println("long keeps short's deadline:", d3.Equal(d2))

	<-long.Done()
	fmt.Println(long.Err(), errors.Is(long.Err(), context.DeadlineExceeded))
	fmt.Println("parent:", parent.Err())

	// WithTimeoutCause records why the deadline was set.
	c, cancelC := context.WithTimeoutCause(context.Background(), 20*time.Millisecond, errSlowStore)
	defer cancelC()
	<-c.Done()
	fmt.Println(c.Err(), "/", context.Cause(c))

	// WithDeadline takes an absolute time; a deadline in the past cancels at once.
	past, cancelPast := context.WithDeadline(context.Background(), time.Now().Add(-time.Second))
	defer cancelPast()
	fmt.Println(past.Err())

	// Calling cancel releases the timer early and leaves Canceled as the error.
	t, cancelT := context.WithTimeout(context.Background(), time.Hour)
	cancelT()
	fmt.Println(t.Err())
}

short earlier than parent: true
long keeps short's deadline: true
context deadline exceeded true
parent: <nil>
context deadline exceeded / store did not answer within the budget
context deadline exceeded
context canceled

package main

import (
	"context"
	"fmt"
	"sync"
	"time"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())

	var wg sync.WaitGroup
	wg.Add(1)
	// AfterFunc runs f in its own goroutine once ctx is done.
	stop := context.AfterFunc(ctx, func() {
		defer wg.Done()
		fmt.Println("cleanup after:", ctx.Err())
	})
	cancel()
	wg.Wait()
	fmt.Println("stop after run returns:", stop())

	// stop prevents f from running when it is called first.
	ctx2, cancel2 := context.WithCancel(context.Background())
	stop2 := context.AfterFunc(ctx2, func() { fmt.Println("never printed") })
	fmt.Println("stopped before cancel:", stop2())
	cancel2()
	time.Sleep(50 * time.Millisecond)

	// WithoutCancel keeps values but drops cancellation and the deadline.
	type key struct{}
	parent, cancelP := context.WithTimeout(context.WithValue(context.Background(), key{}, "req-7"), time.Millisecond)
	defer cancelP()
	<-parent.Done()
	detached := context.WithoutCancel(parent)
	_, hasDeadline := detached.Deadline()
	fmt.Println("parent:", parent.Err())
	fmt.Println("detached:", detached.Err(), detached.Done() == nil, hasDeadline, detached.Value(key{}))
}

cleanup after: context canceled
stop after run returns: false
stopped before cancel: true
parent: context deadline exceeded
detached: <nil> true false req-7

package main

import (
	"context"
	"errors"
	"fmt"
	"sync"
	"time"
)

type key struct{}

// audit must finish even if the request that triggered it is cancelled,
// so it detaches from the request's cancellation but keeps its values.
func audit(ctx context.Context, wg *sync.WaitGroup, action string) {
	detached := context.WithoutCancel(ctx)
	wg.Go(func() {
		bounded, cancel := context.WithTimeout(detached, 2*time.Second)
		defer cancel()
		select {
		case <-time.After(30 * time.Millisecond): // the slow write
			fmt.Printf("audited %q for %v (request ctx: %v)\n", action, bounded.Value(key{}), ctx.Err())
		case <-bounded.Done():
			fmt.Println("audit lost:", bounded.Err())
		}
	})
}

func main() {
	req, cancel := context.WithCancel(context.WithValue(context.Background(), key{}, "req-9"))
	var wg sync.WaitGroup
	audit(req, &wg, "lend 9780441172719")
	cancel() // the client disconnects right away
	wg.Wait()

	// First-error-wins fan-out using only the standard library.
	ctx, stop := context.WithCancelCause(context.Background())
	defer stop(nil)
	var mu sync.Mutex
	var failures []string
	var group sync.WaitGroup
	for i, isbn := range []string{"9780441172719", "bad-isbn", "9780140449136"} {
		group.Go(func() {
			if isbn == "bad-isbn" {
				stop(fmt.Errorf("import item %d: %w", i, errors.New("invalid ISBN")))
				return
			}
			select {
			case <-time.After(10 * time.Second):
			case <-ctx.Done():
				mu.Lock()
				failures = append(failures, isbn)
				mu.Unlock()
			}
		})
	}
	group.Wait()
	fmt.Println("cause:", context.Cause(ctx))
	fmt.Println("abandoned items:", len(failures))
}

audited "lend 9780441172719" for req-9 (request ctx: context canceled)
cause: import item 1: invalid ISBN
abandoned items: 2

package main

import (
	"context"
	"fmt"
)

type Book struct{ Title string }

// Books streams books from the source until it is exhausted or ctx is done.
// The goroutine always exits: either the source ends or ctx is cancelled.
func Books(ctx context.Context, titles []string) <-chan Book {
	out := make(chan Book)
	go func() {
		defer close(out)
		for _, t := range titles {
			select {
			case out <- Book{Title: t}:
			case <-ctx.Done():
				return
			}
		}
	}()
	return out
}

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()
	titles := []string{"Dune", "Emma", "Ulysses", "Hamlet", "Beloved"}
	n := 0
	for b := range Books(ctx, titles) {
		n++
		fmt.Println("got", b.Title)
		if n == 2 {
			cancel() // stop the producer; it releases its goroutine
			break
		}
	}
	fmt.Println("stopped after", n, "books:", ctx.Err())
}

got Dune
got Emma
stopped after 2 books: context canceled

package main

import (
	"context"
	"fmt"
	"time"
)

// checksum models CPU-bound work: it polls ctx.Err every 1024 iterations
// instead of on every one, because the check is cheap but not free.
func checksum(ctx context.Context, data []byte) (uint32, error) {
	var sum uint32
	for i, b := range data {
		if i%1024 == 0 {
			if err := ctx.Err(); err != nil {
				return 0, fmt.Errorf("checksum stopped at byte %d: %w", i, err)
			}
		}
		sum = sum*31 + uint32(b)
	}
	return sum, nil
}

// pause waits for d or until ctx is done, unlike time.Sleep which cannot be interrupted.
func pause(ctx context.Context, d time.Duration) error {
	t := time.NewTimer(d)
	defer t.Stop()
	select {
	case <-t.C:
		return nil
	case <-ctx.Done():
		return context.Cause(ctx)
	}
}

func main() {
	data := make([]byte, 1<<20)

	ctx, cancel := context.WithCancel(context.Background())
	sum, err := checksum(ctx, data)
	fmt.Println(sum, err)

	cancel()
	_, err = checksum(ctx, data)
	fmt.Println(err)

	short, cancelShort := context.WithTimeout(context.Background(), 20*time.Millisecond)
	defer cancelShort()
	start := time.Now()
	err = pause(short, time.Hour)
	fmt.Println(err, time.Since(start) < 5*time.Second)
}

0 <nil>
checksum stopped at byte 0: context canceled
context deadline exceeded true

package main

import (
	"context"
	"errors"
	"fmt"
)

type ISBN string

type Book struct {
	ISBN  ISBN
	Title string
}

// Store is the shelf catalogue; every method that may block takes a Context
// as its first parameter, named ctx.
type Store interface {
	Get(ctx context.Context, isbn ISBN) (Book, error)
	Put(ctx context.Context, b Book) error
}

type memStore struct{ books map[ISBN]Book }

func (s *memStore) Get(ctx context.Context, isbn ISBN) (Book, error) {
	if err := ctx.Err(); err != nil {
		return Book{}, err
	}
	b, ok := s.books[isbn]
	if !ok {
		return Book{}, errors.New("not found")
	}
	return b, nil
}

func (s *memStore) Put(ctx context.Context, b Book) error {
	if err := ctx.Err(); err != nil {
		return err
	}
	s.books[b.ISBN] = b
	return nil
}

func main() {
	var st Store = &memStore{books: map[ISBN]Book{}}
	ctx := context.Background()
	fmt.Println(st.Put(ctx, Book{"9780441172719", "Dune"}))
	b, err := st.Get(ctx, "9780441172719")
	fmt.Println(b, err)

	cctx, cancel := context.WithCancel(ctx)
	cancel()
	_, err = st.Get(cctx, "9780441172719")
	fmt.Println(err)
}

<nil>
{9780441172719 Dune} <nil>
context canceled

package main

import (
	"context"
	"fmt"
	"log/slog"
	"os"
)

// Unexported key types make collisions with other packages impossible:
// even a string key "request-id" from another package is a different key.
type ctxKey int

const (
	requestIDKey ctxKey = iota
	memberKey
)

// WithRequestID returns a copy of ctx carrying the request ID.
func WithRequestID(ctx context.Context, id string) context.Context {
	return context.WithValue(ctx, requestIDKey, id)
}

// RequestIDFrom extracts the request ID, if any.
func RequestIDFrom(ctx context.Context) (string, bool) {
	id, ok := ctx.Value(requestIDKey).(string)
	return id, ok
}

// WithMember and MemberFrom follow the same pattern for a second key.
func WithMember(ctx context.Context, m string) context.Context {
	return context.WithValue(ctx, memberKey, m)
}

func MemberFrom(ctx context.Context) (string, bool) {
	m, ok := ctx.Value(memberKey).(string)
	return m, ok
}

func main() {
	ctx := WithRequestID(context.Background(), "req-42")
	ctx = WithMember(ctx, "ana")

	id, ok := RequestIDFrom(ctx)
	fmt.Println(id, ok)
	m, ok := MemberFrom(ctx)
	fmt.Println(m, ok)

	_, ok = RequestIDFrom(context.Background())
	fmt.Println("missing:", ok)

	// A string key from "another package" does not collide with ours.
	foreign := context.WithValue(ctx, "request-id", "someone-else")
	id, _ = RequestIDFrom(foreign)
	fmt.Println(id, foreign.Value("request-id"))

	// Context values are visible to the whole call tree below, so a logging
	// helper can use them without every function taking a logger parameter.
	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
		ReplaceAttr: func(_ []string, a slog.Attr) slog.Attr {
			if a.Key == slog.TimeKey {
				return slog.Attr{}
			}
			return a
		},
	}))
	if id, ok := RequestIDFrom(ctx); ok {
		logger = logger.With("request_id", id)
	}
	logger.InfoContext(ctx, "lending book", "isbn", "9780441172719")
}

req-42 true
ana true
missing: false
req-42 someone-else
level=INFO msg="lending book" request_id=req-42 isbn=9780441172719

package main

import (
	"context"
	"fmt"
)

type key struct{}

func main() {
	ctx := context.Background()
	for i := range 3 {
		ctx = context.WithValue(ctx, i, fmt.Sprint("v", i))
	}
	ctx = context.WithValue(ctx, key{}, "deep")
	fmt.Println(ctx)
	fmt.Println(ctx.Value(0), ctx.Value(key{}), ctx.Value(99))
}

context.Background.WithValue(int, v0).WithValue(int, v1).WithValue(int, v2).WithValue(main.key, deep)
v0 deep <nil>

package main

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"net/http/httptest"
	"time"
)

func main() {
	observed := make(chan error, 1)

	mux := http.NewServeMux()
	mux.HandleFunc("GET /books/{isbn}", func(w http.ResponseWriter, r *http.Request) {
		// r.Context() is cancelled when the client goes away, when the
		// request is cancelled (HTTP/2) or when ServeHTTP returns.
		select {
		case <-r.Context().Done():
			observed <- context.Cause(r.Context())
		case <-time.After(time.Minute):
			fmt.Fprintln(w, "slow answer")
		}
	})
	mux.HandleFunc("GET /fast/{isbn}", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "book %s\n", r.PathValue("isbn"))
	})
	srv := httptest.NewServer(mux)
	defer srv.Close()

	// The client side: the request carries a context with a timeout.
	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
	defer cancel()
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, srv.URL+"/books/9780441172719", nil)
	if err != nil {
		panic(err)
	}
	_, err = srv.Client().Do(req)
	fmt.Println("client error is deadline:", errors.Is(err, context.DeadlineExceeded))

	select {
	case cause := <-observed:
		fmt.Println("server saw:", cause)
	case <-time.After(10 * time.Second):
		fmt.Println("server never noticed")
	}

	// A normal request still works, and Response.Body must be closed.
	req2, _ := http.NewRequestWithContext(context.Background(), http.MethodGet, srv.URL+"/fast/9780441172719", nil)
	resp, err := srv.Client().Do(req2)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	buf := make([]byte, 64)
	n, _ := resp.Body.Read(buf)
	fmt.Print(string(buf[:n]))
}

client error is deadline: true
server saw: context canceled
book 9780441172719

package main

import (
	"context"
	"fmt"
	"net"
	"net/http"
	"net/http/httptest"
	"time"
)

type reqKey struct{}

func main() {
	var seen string
	mux := http.NewServeMux()
	mux.HandleFunc("GET /ping", func(w http.ResponseWriter, r *http.Request) {
		seen, _ = r.Context().Value(reqKey{}).(string)
		fmt.Fprintln(w, "pong")
	})
	srv := httptest.NewUnstartedServer(mux)
	// BaseContext sets the root of every request context; ConnContext runs per connection.
	srv.Config.BaseContext = func(_ net.Listener) context.Context {
		return context.WithValue(context.Background(), reqKey{}, "server-root")
	}
	srv.Start()
	defer srv.Close()

	c, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	req, _ := http.NewRequestWithContext(c, http.MethodGet, srv.URL+"/ping", nil)
	resp, err := srv.Client().Do(req)
	if err != nil {
		panic(err)
	}
	resp.Body.Close()
	fmt.Println(resp.Status, seen)
}

200 OK server-root

package main

import (
	"context"
	"database/sql"
	"fmt"
	"time"
)

// Title looks up a title with a per-query budget derived from the caller's context.
// It is compiled and vetted, but not run: running it needs a database driver and a DSN.
func Title(ctx context.Context, db *sql.DB, isbn string) (string, error) {
	ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
	defer cancel()

	var title string
	err := db.QueryRowContext(ctx, "SELECT title FROM books WHERE isbn = $1", isbn).Scan(&title)
	if err != nil {
		return "", fmt.Errorf("title %s: %w", isbn, err)
	}
	return title, nil
}

func main() {
	var db *sql.DB // opened with sql.Open and a driver in a real program
	_ = db
	fmt.Println("see the function Title")
}

see the function Title

package main

import (
	"context"
	"errors"
	"fmt"
	"os"
	"os/exec"
	"time"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
	defer cancel()

	cmd := exec.CommandContext(ctx, "sleep", "30")
	cmd.WaitDelay = time.Second // how long Wait lets I/O drain after cancellation
	start := time.Now()
	err := cmd.Run()
	fmt.Println("error:", err)
	fmt.Println("deadline:", errors.Is(ctx.Err(), context.DeadlineExceeded))
	fmt.Println("fast:", time.Since(start) < 10*time.Second)

	// Cancel lets you choose a gentler signal than Kill.
	ctx2, cancel2 := context.WithCancel(context.Background())
	cmd2 := exec.CommandContext(ctx2, "sleep", "30")
	cmd2.Cancel = func() error {
		fmt.Println("custom cancel: sending interrupt")
		return cmd2.Process.Signal(os.Interrupt)
	}
	if err := cmd2.Start(); err != nil {
		panic(err)
	}
	cancel2()
	fmt.Println("wait:", cmd2.Wait())
}

error: signal: killed
deadline: true
fast: true
custom cancel: sending interrupt
wait: signal: interrupt

package main

import (
	"context"
	"fmt"
	"os"
	"os/signal"
	"syscall"
	"time"
)

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	// Simulate an operator pressing Ctrl+C: send ourselves SIGINT.
	go func() {
		time.Sleep(50 * time.Millisecond)
		syscall.Kill(syscall.Getpid(), syscall.SIGINT)
	}()

	select {
	case <-ctx.Done():
		fmt.Println("Err:  ", ctx.Err())
		fmt.Println("Cause:", context.Cause(ctx))
	case <-time.After(30 * time.Second):
		fmt.Println("no signal arrived")
	}

	// stop restores default behaviour: a second Ctrl+C now kills the process.
	stop()
	fmt.Println("shutdown complete")
}

Err:   context canceled
Cause: interrupt signal received
shutdown complete

// Fragment: needs golang.org/x/sync v0.24.0.
func ImportAll(ctx context.Context, isbns []string, fetch func(context.Context, string) error) error {
	g, ctx := errgroup.WithContext(ctx)
	g.SetLimit(8) // at most 8 fetches in flight
	for _, isbn := range isbns {
		g.Go(func() error {
			return fetch(ctx, isbn) // ctx is cancelled when any call returns an error
		})
	}
	return g.Wait() // first error, after every goroutine has returned
}

package watch

import (
	"context"
	"time"
)

// Poll calls check every interval until it reports true or ctx is done.
func Poll(ctx context.Context, interval time.Duration, check func() bool) error {
	t := time.NewTicker(interval)
	defer t.Stop()
	for {
		if check() {
			return nil
		}
		select {
		case <-t.C:
		case <-ctx.Done():
			return context.Cause(ctx)
		}
	}
}

package watch

import (
	"context"
	"errors"
	"sync"
	"testing"
	"testing/synctest"
	"time"
)

// t.Context is cancelled just before cleanup functions run, so goroutines
// started by the test can stop themselves without an explicit cancel.
func TestPollStopsWithTest(t *testing.T) {
	stopped := make(chan error, 1)
	go func() {
		stopped <- Poll(t.Context(), time.Millisecond, func() bool { return false })
	}()
	t.Cleanup(func() {
		// Cleanup runs after t.Context() was cancelled.
		select {
		case err := <-stopped:
			if !errors.Is(err, context.Canceled) {
				t.Errorf("got %v, want Canceled", err)
			}
		case <-time.After(10 * time.Second):
			t.Error("poller did not stop")
		}
	})
}

// synctest runs the test in a bubble with a fake clock, so a 55-minute
// timeout takes no real time and the result is deterministic.
func TestPollTimeout(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		ctx, cancel := context.WithTimeout(t.Context(), 55*time.Minute)
		defer cancel()

		var mu sync.Mutex
		calls := 0
		err := Poll(ctx, 10*time.Minute, func() bool {
			mu.Lock()
			defer mu.Unlock()
			calls++
			return false
		})
		if !errors.Is(err, context.DeadlineExceeded) {
			t.Fatalf("got %v, want DeadlineExceeded", err)
		}
		t.Logf("check ran %d times before the deadline", calls)
	})
}

=== RUN   TestPollStopsWithTest
--- PASS: TestPollStopsWithTest (0.00s)
=== RUN   TestPollTimeout
    watch_test.go:50: check ran 6 times before the deadline
--- PASS: TestPollTimeout (0.00s)
PASS
ok  	example.com/shelf/watch	0.058s