Generic Methods

This is the headline, and it is a real language change: a method declaration may now declare its own type parameters.

Before 1.27, type parameters could only appear on a function or on the type itself. If you wanted a generic helper that logically belonged to a type, your only option was a package-level function:

// Go 1.26 and earlier: the helper lives in the package namespace,
// even though it only makes sense for *Rand.
func N[Int intType](r *rand.Rand, n Int) Int

Now it can live where it belongs. math/rand/v2 is the standard library’s own example — it gained a generic method alongside the existing generic function:

// Go 1.27
func (r *Rand) N[Int intType](n Int) Int

Which means this now compiles:

r := rand.New(rand.NewPCG(1, 2))

var d time.Duration = r.N(time.Second)  // method, inferred as time.Duration
var i int32         = r.N(int32(100))   // same method, different instantiation

The practical effect is that you can stop writing pkg.DoThing(x, ...) for operations that are conceptually x.DoThing(...). Anywhere you have a container, a client, or a builder that needed a package-level generic helper, that helper can now be a method.

Two limits worth knowing before you plan a refactor around it:

• Interfaces cannot declare type parameters on their methods, and an interface method cannot be satisfied by a generic method. So this does not give you generic interfaces through the back door; the method set of an interface is still fully concrete.
• It is a method type parameter, distinct from the receiver’s. func (c *Cache[K, V]) MapTo[T any](...) has three type parameters in play, two from the receiver and one from the method.

If you have been writing the awkward package-level workarounds I described in how Golang generics minimize the amount of code you need to write, this is the release where a lot of that gets to move inside the type.

Two smaller language changes shipped alongside it. A key in a struct literal may now be any valid field selector, not just a top-level field name — which makes literals for structs with embedded types far less irritating. And function type inference is generalised to every context where a generic function is assigned to, or converted to, a matching function type, so a class of “cannot infer” errors simply disappears.

encoding/json/v2

The JSON rewrite is in, as two packages:

• encoding/json/v2 — the high-level API you already know, redesigned.
• encoding/json/jsontext — lower-level syntactic processing, with an Encoder and Decoder that work in terms of Token and Value and hold a state machine guaranteeing the JSON is valid.

The v2 entry points take variadic options:

import "encoding/json/v2"

b, err := json.Marshal(v,
    json.Deterministic(true),          // stable map ordering
    json.OmitZeroStructFields(true),
)

err = json.Unmarshal(data, &v,
    json.RejectUnknownMembers(true),   // strict decoding, no silent drops
)

Alongside Marshal and Unmarshal there are MarshalWrite / UnmarshalRead for an io.Writer / io.Reader, and MarshalEncode / UnmarshalDecode for driving a jsontext.Encoder / Decoder directly. That last pair is what you want for streaming, and it is a much better story than v1’s json.Decoder ever was.

The defaults are stricter, which is the whole point. v2 rejects invalid UTF-8 in strings and rejects duplicate names within an object — both of which v1 quietly accepted. That is more interoperable and it closes a genuine class of parser-differential bugs.

RejectUnknownMembers(true) deserves a callout for anyone writing an API. v1’s default of silently discarding unknown fields is how a typo in a client’s request body turns into a field that is quietly zero, and then into a support ticket. Making that an error at the boundary is the same instinct as the sentinel errors in error handling in Go: fail where the information is, not three layers down.

encoding/json v1 is not going anywhere, and it gained a matching set of options with names that tell you exactly what they are for — CallMethodsWithLegacySemantics, OmitEmptyWithLegacySemantics, FormatDurationAsNano, ParseTimeWithLooseRFC3339 and friends. That is the migration path: move to v2, and where behaviour differs in a way you depend on, opt back into the v1 semantics explicitly rather than discovering the difference in production.

One thing to be deliberate about: v2’s stricter parsing is a behaviour change at your HTTP boundary. A client that has been sending duplicate keys or malformed UTF-8 and getting away with it will start getting errors. That is correct, and it is still worth knowing before you flip it on a live service. Point a load test at it first — the setup in an easy way to load test your web apps is enough to see whether real traffic trips the new rules.

A uuid Package

There is now a uuid package in the standard library. The whole API is small enough to quote:

type UUID [16]byte

func New() UUID                        // the recommended default
func NewV4() UUID                      // random
func NewV7() UUID                      // time-ordered
func Parse(string) (UUID, error)
func MustParse(string) UUID
func Nil() UUID
func Max() UUID

func (UUID) String() string
func (UUID) Compare(UUID) int
func (UUID) MarshalText() ([]byte, error)
func (UUID) AppendText([]byte) ([]byte, error)
func (*UUID) UnmarshalText([]byte) error

NewV7 is the one to reach for when the UUID is a database key. Version 7 is time-ordered, so generated values sort roughly by creation time — which keeps B-tree index inserts near the right-hand edge instead of scattering them across the whole index the way v4 does. If you have ever watched write throughput degrade on a table with a random-UUID primary key, that is the problem v7 exists to solve.

Compare returning an int means it drops straight into slices.SortFunc, and the TextMarshaler / TextUnmarshaler implementation means it round-trips through JSON and database/sql without a wrapper type.

The obvious question: does this kill github.com/google/uuid? Not immediately — plenty of code depends on its wider surface. But for the common case of “I need a v4 or v7 UUID, and I need to parse one”, that is now a dependency you can delete.

Goroutine Leak Profiles, Generally Available

The goroutineleak profile, experimental in 1.26, is now GA in runtime/pprof and exposed at /debug/pprof/goroutineleak.

It reports goroutines blocked on a concurrency primitive that cannot possibly become unblocked. The detection is clever: it piggybacks on the garbage collector. If goroutine G is blocked on primitive P, and P is unreachable from any runnable goroutine — or from any goroutine those could unblock — then nothing can ever signal P, so G is leaked.

import _ "net/http/pprof"

// then:
//   go tool pprof http://localhost:6060/debug/pprof/goroutineleak

The reachability trick is also the limitation, and the release notes say so plainly: leaks caused by blocking on a primitive that is still reachable through a global, or through a runnable goroutine’s locals, will not be detected. It catches a large class, not all of them.

Still, this is the first tool that turns “we think we have a goroutine leak somewhere” into a list. The failure modes it finds are exactly the ones from worker pools in Go with errgroup — a worker blocked forever on a send to a channel nobody is reading — and the ones a missing <-ctx.Done() produces, which I wrote about in understanding Golang context.

Free Performance

The compiler now emits calls to size-specialised allocation routines, cutting the cost of small allocations (under 80 bytes) by up to 30%. The release notes are honest about what that means end to end: roughly 1% on allocation-heavy programs, and about 60 KB more binary, regardless of workload.

One percent for a recompile is a good trade. If it causes you trouble, GOEXPERIMENT=nosizespecializedmalloc turns it off at build time — but note that escape hatch is expected to be removed in Go 1.28, so treat it as a window to file a bug, not a setting to keep.

Smaller Things Worth Knowing

That last one is quietly excellent. It is the failure mode where your code builds on your machine and breaks on a builder pinned to an older Go — the same class of problem I hit deploying this blog, where a template function that did not exist in the CI toolchain failed a build that was green locally.

Two for Later

crypto/mldsa implements ML-DSA, the post-quantum signature scheme standardised as FIPS 204, with the three parameter sets MLDSA44(), MLDSA65() and MLDSA87(). Unless you have a compliance requirement you will not touch it this year, but it being in the standard library is what makes migration a normal task rather than a project.

simd is an experimental package behind GOEXPERIMENT=simd, providing portable, vector-size-agnostic SIMD types like Int8s and Float32s that use hardware instructions where available. Experimental means experimental — but portable SIMD in Go is a genuinely interesting direction.

Should You Upgrade?

Yes, and the calculus is unusually simple:

• The Go 1 compatibility promise holds; almost everything compiles unchanged.
• You get ~1% on allocation-heavy code for a recompile.
• goroutineleak is worth the upgrade on its own for any service running long-lived goroutines.
• Generic methods and JSON v2 are opt-in. Nothing forces you to rewrite anything.

The only change that needs a moment’s thought is JSON v2’s stricter parsing, and only if you adopt it at a public boundary. Everything else is additive.

Conclusion

Generic methods close a gap that has been awkward since generics landed in 1.18, and they will quietly improve a lot of library APIs over the next year. JSON v2 is the rarer thing: a second attempt at a core package that gets to fix the defaults, with an explicit escape hatch back to the old behaviour. And a uuid package removes a dependency from nearly every service I have written.

Not bad for a release the notes describe as “mostly implementation”.

The Loop, In Full

Here is a complete manual loop. It is worth reading once even if you end up using the SDK’s runner, because everything that goes wrong later is easier to diagnose when you know this shape. It assumes you already have a client and know how to read a response — if not, start with calling an LLM from Go.

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/anthropics/anthropic-sdk-go"
)

func main() {
    client := anthropic.NewClient()

    addTool := anthropic.ToolParam{
        Name:        "add",
        Description: anthropic.String("Add two integers"),
        InputSchema: anthropic.ToolInputSchemaParam{
            Properties: map[string]any{
                "a": map[string]any{"type": "integer"},
                "b": map[string]any{"type": "integer"},
            },
        },
    }
    tools := []anthropic.ToolUnionParam{{OfTool: &addTool}}

    messages := []anthropic.MessageParam{
        anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")),
    }

    for {
        resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
            Model:     "claude-opus-5",
            MaxTokens: 16000,
            Messages:  messages,
            Tools:     tools,
        })
        if err != nil {
            log.Fatal(err)
        }

        // Append the assistant turn BEFORE handling the tool calls.
        messages = append(messages, resp.ToParam())

        var toolResults []anthropic.ContentBlockParamUnion
        for _, block := range resp.Content {
            switch variant := block.AsAny().(type) {
            case anthropic.TextBlock:
                fmt.Println(variant.Text)
            case anthropic.ToolUseBlock:
                var in struct {
                    A int `json:"a"`
                    B int `json:"b"`
                }
                // block.Input is raw JSON — parse it, never string-match it.
                if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil {
                    log.Fatal(err)
                }
                result := fmt.Sprintf("%d", in.A+in.B)
                toolResults = append(toolResults,
                    anthropic.NewToolResultBlock(block.ID, result, false))
            }
        }

        if resp.StopReason != anthropic.StopReasonToolUse {
            break
        }

        // All results from this turn go back in ONE user message.
        messages = append(messages, anthropic.NewUserMessage(toolResults...))
    }
}

Five things in there are load-bearing, and four of them are easy to get subtly wrong.

resp.ToParam() converts the response into a history entry. You must append the assistant’s turn — including its tool-call blocks — before you send the results, or the next request has results referring to a call that does not exist in the conversation.

Parse the tool input; never pattern-match the raw string. variant.JSON.Input.Raw() gives you the JSON to unmarshal. Current models vary their JSON string escaping (Unicode escapes, escaped forward slashes), so anything doing strings.Contains on the serialised input is a bug waiting for a release.

All tool results go back in a single user message. anthropic.NewUserMessage is variadic for exactly this reason. Splitting results across several messages technically works, and it quietly teaches the model to stop issuing parallel calls — which halves your throughput for no visible reason.

StopReason is the exit condition, not “did I see any tool blocks”. Check it after you have appended the results, not before.

Every tool call needs a result. If the model asked for three tools and you return two results, the next request is malformed. Including for the one that failed — which brings us to the most useful trick in this whole article.

Errors Are Results, Not Exceptions

The instinct when a tool fails is to abort the loop. Usually that is wrong. Hand the failure back to the model as a tool result flagged as an error, and it will very often recover on its own — retry with a corrected argument, try a different tool, or tell the user what went wrong:

out, err := h.run(ctx, variant)
if err != nil {
    // isError = true. The model sees the failure and can adapt.
    toolResults = append(toolResults,
        anthropic.NewToolResultBlock(block.ID, err.Error(), true))
    continue
}
toolResults = append(toolResults, anthropic.NewToolResultBlock(block.ID, out, false))

That third parameter is isError. Getting this right turns a class of hard failures into self-correcting ones.

One caveat worth stating plainly: the error text goes into the model’s context, so do not put a raw database error with connection strings and internal hostnames in there. Return the error you would show a careful external user. This is the same discipline as deciding what a sentinel error exposes at your HTTP boundary, which I covered in error handling in Go.

Let the SDK Drive

Once you understand the loop, you mostly do not want to maintain it. The Go SDK’s tool runner handles the iteration, and generates the JSON schema from your struct tags:

import "github.com/anthropics/anthropic-sdk-go/toolrunner"

type GetWeatherInput struct {
    City string `json:"city" jsonschema:"required,description=The city name"`
}

weatherTool, err := toolrunner.NewBetaToolFromJSONSchema(
    "get_weather",
    "Get current weather for a city",
    func(ctx context.Context, in GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
        return anthropic.BetaToolResultBlockParamContentUnion{
            OfText: &anthropic.BetaTextBlockParam{
                Text: fmt.Sprintf("The weather in %s is sunny, 22°C", in.City),
            },
        }, nil
    },
)
if err != nil {
    return err
}

runner := client.Beta.Messages.NewToolRunner(
    []anthropic.BetaTool{weatherTool},
    anthropic.BetaToolRunnerParams{
        BetaMessageNewParams: anthropic.BetaMessageNewParams{
            Model:     "claude-opus-5",
            MaxTokens: 16000,
            Messages: []anthropic.BetaMessageParam{
                anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Kyiv?")),
            },
        },
        MaxIterations: 5,
    },
)

message, err := runner.RunToCompletion(ctx)

Note the namespace: this lives under client.Beta.Messages, and the types are the Beta* variants — BetaTextBlock, not TextBlock. Mixing the two is the most common compile error here.

MaxIterations is not optional decoration. Without a ceiling, a model that gets into a retry rut can loop until your context deadline, and you pay for every turn. Set it to the smallest number that lets legitimate work finish.

If you need to inspect or gate each step — approvals, audit logging, a check before a destructive tool runs — you do not have to drop back to a manual loop. The runner exposes NextMessage() and an All() iterator so you can step it and look at each message, and its Params field lets you adjust the next request. Reach for the manual loop only when you want control the runner genuinely does not expose.

Running Tools Concurrently — With a Limit

When the model asks for four tools in one turn, running them sequentially wastes the whole point. But the naive concurrent version is the same mistake Go developers make everywhere else:

// Don't. One turn can ask for many tools; this has no ceiling.
for _, call := range calls {
    go run(call)
}

Use a bounded group. The results still have to come back in one message, in a fixed order, so index into a preallocated slice rather than appending from goroutines:

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

results := make([]anthropic.ContentBlockParamUnion, len(calls))

g, gctx := errgroup.WithContext(ctx)
g.SetLimit(4) // whatever your slowest downstream can absorb

for i, call := range calls {
    g.Go(func() error {
        out, err := h.run(gctx, call)
        if err != nil {
            // Not a group error: hand it to the model instead.
            results[i] = anthropic.NewToolResultBlock(call.ID, err.Error(), true)
            return nil
        }
        results[i] = anthropic.NewToolResultBlock(call.ID, out, false)
        return nil
    })
}
if err := g.Wait(); err != nil {
    return err
}

messages = append(messages, anthropic.NewUserMessage(results...))

Each goroutine writes one distinct slice element, so no mutex is needed — different elements are different memory. Appending to a shared slice from several goroutines is a different story, and so is writing to a shared map; concurrent map writing and reading in Go has the failure mode in detail.

Notice that a tool failure returns nil from g.Go. Returning the error would cancel gctx and kill the sibling tool calls, when what you actually want is to report that one failure to the model and let the others finish. The full set of tradeoffs around SetLimit and error propagation is in worker pools in Go with errgroup.

Designing the Tools Themselves

The loop is the easy part. Tool design is where agents get good or stay bad.

The description is the API documentation, and its reader is the model. A tool called search described as “searches” will be called wrongly and often. Say what it searches, what it returns, and when not to use it. Most “the agent keeps doing the wrong thing” problems are description problems.

Fewer, broader tools beat many narrow ones. Twenty tools that each wrap one endpoint force the model to plan a long chain and give it twenty chances to pick wrong. One query_orders tool with a few well-named parameters usually outperforms get_order, list_orders_by_user, list_orders_by_date and count_orders.

Constrain the schema. Enums, required fields and explicit types are enforced before your handler runs. Every constraint you express in the schema is a class of invalid call you never have to validate by hand.

Make results terse. Tool results occupy context on every subsequent turn of the loop. Returning a 400-row JSON dump costs you tokens on turn two, turn three and turn four. Return the fields the model needs to decide what to do next, and nothing else.

Be deliberate about side effects. The model will call your tools in orders you did not anticipate. Anything that writes, sends, charges or deletes wants an approval gate — step the runner and confirm — or, at minimum, idempotency so a double call is harmless.

Guardrails That Actually Matter in Production

A tool loop has a cost profile unlike a normal handler: every iteration resends the whole conversation. The bill grows quadratically with the number of turns if you are not careful, and three things keep it honest.

Cap the iterations. MaxIterations on the runner, or a counter in your manual loop. Non-negotiable.

Bound the wall clock. A deadline on the context that covers the whole loop, not each request:

ctx, cancel := context.WithTimeout(ctx, 5*time.Minute)
defer cancel()

Cache the prefix. Every turn resends the system prompt and the full history. Without prompt caching you pay full price for all of it, every iteration — this is where agent loops get expensive, and it is the one lever with no quality tradeoff at all. It gets its own article.

Then there is the interaction between concurrency and rate limits. A pool of four tool calls, times however many concurrent user requests, times however many turns each — an agent loop is a very effective way to discover your own rate limits. The token-bucket approach from rate limiting Go APIs works just as well pointed at your own outbound calls as at inbound traffic.

Observability, Or You Are Flying Blind

When a loop misbehaves, you need to see what the model actually saw. Log per iteration:

slog.Info("agent turn",
    "iteration", i,
    "stop_reason", resp.StopReason,
    "tools_called", toolNames,
    "input_tokens", resp.Usage.InputTokens,
    "output_tokens", resp.Usage.OutputTokens,
    "cache_read", resp.Usage.CacheReadInputTokens,
)

With a request-scoped logger carrying the conversation id (the pattern from the slog post), you can pull the entire trajectory of one run out of your logs — which is the difference between “the agent is flaky” and “on turn three it called search with an empty query because the description was ambiguous”.

Pitfalls

Conclusion

The loop is twenty lines and you should write it once by hand, then let the runner own it. After that, the work that actually improves an agent is not loop code at all: sharper tool descriptions, tighter schemas, terser results, a hard iteration cap, and enough logging to reconstruct a bad run. The interesting engineering is in the tools, not the loop around them.

The Problem With the Obvious Version

// Do not ship this.
func fetchAll(urls []string) {
    var wg sync.WaitGroup
    for _, url := range urls {
        wg.Add(1)
        go func() {
            defer wg.Done()
            fetch(url)
        }()
    }
    wg.Wait()
}

Three separate problems:

1. No limit. len(urls) concurrent requests. The remote service rate-limits you, or your file descriptors run out, or both.
2. No errors. fetch returns one and it goes nowhere.
3. No cancellation. If the caller gives up, every goroutine keeps running to completion.

The concurrency itself is not the mistake — the missing back pressure is.

The Classic Channel Pool

The traditional shape is a jobs channel, a fixed number of workers reading from it, and a results channel:

type job struct {
    ID  int
    URL string
}

type result struct {
    JobID int
    Body  []byte
    Err   error
}

func workerPool(ctx context.Context, jobs []job, workers int) []result {
    jobCh := make(chan job)
    resCh := make(chan result, len(jobs))

    var wg sync.WaitGroup
    for i := 0; i < workers; i++ {
        wg.Add(1)
        go func(workerID int) {
            defer wg.Done()
            for j := range jobCh {
                body, err := fetch(ctx, j.URL)
                select {
                case resCh <- result{JobID: j.ID, Body: body, Err: err}:
                case <-ctx.Done():
                    return
                }
            }
        }(i)
    }

    // Feed the workers, stopping early if the caller cancels.
    go func() {
        defer close(jobCh)
        for _, j := range jobs {
            select {
            case jobCh <- j:
            case <-ctx.Done():
                return
            }
        }
    }()

    wg.Wait()
    close(resCh)

    out := make([]result, 0, len(jobs))
    for r := range resCh {
        out = append(out, r)
    }
    return out
}

This is worth understanding because you will read it in a lot of codebases, and because it shows the mechanics plainly. Note two things that are easy to get wrong:

• close(jobCh) is the workers’ exit signal. for j := range jobCh ends when the channel closes. Forget the close and wg.Wait() blocks forever.
• Every channel send is paired with <-ctx.Done(). Without that, a worker sending to a full resCh that nobody is reading leaks for the lifetime of the process.

It is also about forty lines to do something the standard extended library does in eight.

The errgroup Version

golang.org/x/sync/errgroup is a sync.WaitGroup that also collects the first error and cancels its siblings. SetLimit turns it into a bounded pool:

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

func fetchAll(ctx context.Context, urls []string) ([][]byte, error) {
    bodies := make([][]byte, len(urls))

    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(10) // at most 10 in flight

    for i, url := range urls {
        g.Go(func() error {
            body, err := fetch(ctx, url)
            if err != nil {
                return fmt.Errorf("fetch %s: %w", url, err)
            }
            // Each goroutine owns exactly one slot: no mutex needed.
            bodies[i] = body
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return nil, err
    }
    return bodies, nil
}

That is the whole pool. Behaviour worth knowing:

• g.Go blocks once the limit is reached, until a slot frees up. The for loop becomes its own back pressure — no jobs channel needed.
• errgroup.WithContext returns a derived context that is cancelled the moment any goroutine returns a non-nil error. Shadowing ctx with it, as above, is deliberate: every fetch gets the cancellable one.
• g.Wait() returns the first error, and waits for the rest regardless. Later errors are discarded — if you need all of them, collect them yourself (errors.Join is a good fit, see error handling in Go).
• Writing to bodies[i] is safe without a mutex because each goroutine writes one distinct element. Different elements of a slice are different memory; that is not a data race. Appending to a shared slice, or writing to a shared map, absolutely is — see concurrent map writing and reading in Go for what that failure looks like.

A Note on Loop Variables

The example above relies on Go 1.22’s per-iteration loop variables. Before 1.22, i and url were shared across iterations and every goroutine would see the final values — the single most common concurrency bug in Go. On older versions you must copy them:

for i, url := range urls {
    i, url := i, url // required before Go 1.22
    g.Go(func() error { /* ... */ })
}

Since Go 1.22 the copy is unnecessary. Leaving it in is harmless, and I still write it in code that must build on older toolchains. The loop semantics change was one of the more consequential recent additions to the language — I touched on the surrounding rules in mastering Golang for loops.

Streaming Results Instead of Preallocating

Indexing into a preallocated slice only works when you know the number of jobs up front. For a stream, send results down a channel and read them concurrently:

func processStream(ctx context.Context, in <-chan job, workers int) (<-chan result, func() error) {
    out := make(chan result)

    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(workers)

    go func() {
        // Closing `out` after every worker has finished lets the consumer
        // range over it and stop naturally.
        defer close(out)

        for j := range in {
            g.Go(func() error {
                body, err := fetch(ctx, j.URL)
                if err != nil {
                    return fmt.Errorf("job %d: %w", j.ID, err)
                }
                select {
                case out <- result{JobID: j.ID, Body: body}:
                    return nil
                case <-ctx.Done():
                    return ctx.Err()
                }
            })
        }
        _ = g.Wait()
    }()

    return out, g.Wait
}

The consumer ranges over out and then calls the returned function to get the error:

results, wait := processStream(ctx, jobs, 8)
for r := range results {
    save(r)
}
if err := wait(); err != nil {
    return fmt.Errorf("process stream: %w", err)
}

g.Wait() is safe to call more than once — subsequent calls return the same error immediately.

Picking the Limit

There is no universal number, but there is a reliable way to think about it.

CPU-bound work — parsing, hashing, image resizing, compression — saturates at roughly the number of cores. More goroutines just add scheduling overhead:

g.SetLimit(runtime.GOMAXPROCS(0))

I/O-bound work — HTTP calls, database queries, object storage — spends most of its time waiting, so the useful limit is much higher. But it is not “as high as possible”: it is whatever the slowest downstream dependency can absorb. If your database pool has 25 connections, a pool of 200 workers means 175 goroutines queueing on a mutex inside database/sql while your latency graph climbs.

// Match the constraint that actually binds.
g.SetLimit(db.Stats().MaxOpenConnections)

For outbound HTTP, remember that Go’s default transport keeps only 2 idle connections per host. Exceed that and you are opening a fresh TCP connection — plus a TLS handshake — for each extra request:

transport := http.DefaultTransport.(*http.Transport).Clone()
transport.MaxIdleConnsPerHost = 50
transport.MaxConnsPerHost = 50
client := &http.Client{Transport: transport, Timeout: 10 * time.Second}

Then set the pool limit to match. Tuning one without the other gets you nothing.

Whatever you pick, measure it. Run the job at 5, 10, 25 and 50 and look at total wall time and downstream latency — the fastest setting for your batch is often the one that makes everything else on the system slower. Load testing is the honest way to find out; I wrote about a lightweight setup in an easy way to load test your web apps.

Not Every Goroutine Belongs in a Pool

A pool is for a batch of similar work. Some situations want something else:

Waiting on several different things at once — no limit needed, just a group:

g, ctx := errgroup.WithContext(ctx)

var user *User
var orders []Order

g.Go(func() (err error) { user, err = loadUser(ctx, id); return })
g.Go(func() (err error) { orders, err = loadOrders(ctx, id); return })

if err := g.Wait(); err != nil {
    return nil, fmt.Errorf("load profile: %w", err)
}

Three sequential 100ms calls become one 100ms call. This is the highest-value use of errgroup in a typical request handler, and it needs no pool at all.

Work that must happen in order — a pool is the wrong shape entirely; you want a single consumer, like the simple queue implementation I wrote about earlier.

Fire-and-forget background work — resist it. A goroutine started in a request handler outlives the request, holds whatever it captured, and will be killed mid-flight when the process shuts down. If it matters, it belongs in a durable queue; if it does not, do it inline. The same reasoning applies at shutdown time, which I covered in graceful shutdown in Go web services.

Only trying if there is capacity — TryGo starts the goroutine only if a slot is free, and reports whether it did:

if !g.TryGo(func() error { return prefetch(ctx, url) }) {
    // Pool is busy; skip this optional work rather than blocking.
    metrics.PrefetchSkipped.Inc()
}

Pitfalls

Panic recovery is worth spelling out, because one bad input taking down the whole process is a common way for batch jobs to fail:

g.Go(func() (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("panic processing %s: %v", url, r)
        }
    }()
    return process(ctx, url)
})

The named return value err is what makes this work — the deferred function assigns to it after the panic is recovered.

Conclusion

The pattern is small: pick a limit that matches your real bottleneck, use errgroup.WithContext so failures cancel their siblings, return errors instead of logging them, and give every blocking operation a context. Most of the time that is eight lines and no channel plumbing at all. Save the hand-rolled channel pool for the cases where you genuinely need to stream results or vary the shape of the work — and when you do write one, remember to close the jobs channel.

One place this pattern turns up more than you would expect: running the tool calls an LLM asks for, several at a time but not unboundedly — see tool use in Go. And when a pool does leak a worker, Go 1.27’s goroutine leak profile will now name it — what’s new in Go 1.27.

Go was created at Google to solve real-world problems—fast builds, simple deployment, and effortless concurrency—without sacrificing developer happiness. Let’s dive into nine reasons why you should use Golang in 2025 and beyond.

Quick Snapshot: Benefits at a Glance

1. Native Concurrency Model

Go’s goroutines and channels deliver lightweight concurrency without complex thread management. Spawning 100 000 goroutines is commonplace:

func main() {
    wg := sync.WaitGroup{}
    for i := 0; i < 1e5; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            fmt.Println(id)
        }(i)
    }
    wg.Wait()
}

Compare that with traditional threads and locks and the why use Golang answer becomes evident—parallelism is baked into the language.

2. Blazing-Fast Compilation & Execution

Go produces native machine code and compiles large projects in seconds. Faster feedback loops boost productivity, and Go’s runtime performance rivals (and often exceeds) higher-level languages like Python or Node.js.

3. Pragmatic, Readable Syntax

Go deliberately avoids generics-for-everything, implicit magic, and hidden control flow. The result is code that looks similar across companies, which means reading unfamiliar Go is easy.

4. A Batteries-Included Standard Library

Need an HTTP server, JSON encoder, or RSA crypto? It’s already in stdlib. With fewer third-party dependencies, your supply-chain attack surface shrinks.

5. Static Binaries & Effortless Deployment

go build outputs a single, statically linked binary. Drop it in a container scratch image (~10 MB) or onto a bare server—no JVM, no interpreter.

GOOS=linux GOARCH=amd64 go build -ldflags "-s -w" -o app

6. First-Class Tooling Out-of-the-Box

Formatting (go fmt), linting (go vet), profiling (pprof), testing, and coverage are all standard. This uniform toolchain answers why use Golang for teams who value consistency.

7. Memory Safety & Predictable GC

Go’s garbage collector has reached <1 ms 95th percentile pause times while retaining simplicity. With escape analysis and value semantics, many allocations disappear at compile time.

8. Vibrant Ecosystem & Community

Frameworks like Gin, Echo, and Fiber make web development painless; gRPC and Protocol Buffers have first-class support; and cloud providers ship Go SDKs on day one.

9. Proven in Production by Industry Leaders

Google (of course), Netflix, Uber, Cloudflare, Stripe, and many others run latency-critical systems in Go. That track record signals Go’s staying power.

When Not to Use Go

While this article focuses on why to use Golang, balanced engineering requires knowing its limits:

• No generics for higher-kinded types (though basic generics landed in Go 1.18).
• Runtime lacks a mature GUI library.
• Manual error handling (if err != nil) can feel verbose.

If your workload is numerical heavy-compute with tight SIMD requirements or requires sophisticated metaprogramming, Rust or C++ may fit better.

Conclusion

So why use Golang? Because it delivers a rare combination of developer ergonomics, runtime efficiency, and operational simplicity. From microservices to CLI tools, Go empowers teams to ship reliable software—fast.

Ready to give Go a try? Install it, go mod init, and discover firsthand why thousands of engineers choose Golang every day.

If that convinced you, here is where I would start: understanding Golang context for concurrency you can cancel, error handling in Go for the idiom that trips up most newcomers, and one of the easiest ways to host your Go web app for getting the result online. For what the language has picked up lately, see exciting features coming in Go 1.25.

In this article we will demystify the context package, walk through common use-cases, and share production-tested best practices.

Why Context Exists

Go’s lightweight goroutines make it trivial to spin up concurrent work, but once you have hundreds (or thousands) of goroutines you need a structured way to:

1. Cancel unfinished work when a client disconnects or a parent task ends.
2. Enforce upper time bounds to prevent runaway operations.
3. Propagate deadlines deep into the call graph.
4. Attach request-level metadata (trace IDs, auth tokens, etc.) without polluting function signatures.

The context package solves these problems with two core ideas:

• Cancellation propagation via Done() channels.
• Immutable trees—each derived context references its parent, forming a hierarchy that can be cancelled from the root.

Creating and Cancelling Contexts

The building blocks are context.Background() (or context.TODO()), context.WithCancel, context.WithTimeout, and context.WithDeadline.

package main

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

func main() {
    // Start with a root context
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel() // always release resources

    // Fire off a worker goroutine
    go func() {
        select {
        case <-ctx.Done():
            fmt.Println("worker cancelled:", ctx.Err())
            return
        }
    }()

    // Simulate some condition that requires cancellation
    time.Sleep(500 * time.Millisecond)
    cancel()

    time.Sleep(100 * time.Millisecond)
}

Running this prints:

worker cancelled: context canceled

Timeout Helper

context.WithTimeout wraps WithCancel plus a timer:

ctx, cancel := context.WithTimeout(parent, 2*time.Second)
// After 2s: ctx.Err() == context.DeadlineExceeded

Remember to always call the returned cancel—even when the timeout expires—so the timer’s internal resources are freed.

Passing Context Down the Call Stack

The first parameter of every context-aware function should be ctx context.Context:

func fetch(ctx context.Context, url string) ([]byte, error) {
    req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    return io.ReadAll(resp.Body)
}

When ctx is cancelled upstream, http.Client aborts the request automatically.

Deadlines vs. Timeouts

A deadline is an absolute moment (2025-06-16T14:05:00+02:00) while a timeout is a relative duration (5s). Internally both are implemented with WithDeadline, but modelling them correctly communicates intent:

deadline := time.Now().Add(5 * time.Second)
ctx, cancel := context.WithDeadline(parent, deadline)

Storing Values in Context

context.WithValue allows passing request-scoped data without modifying every function signature. Use it sparingly:

// Key type prevents collisions
 type key string
 const traceIDKey key = "traceID"

 ctx := context.WithValue(parent, traceIDKey, "abc-123")

 // Downstream retrieval
 if v := ctx.Value(traceIDKey); v != nil {
     traceID := v.(string)
     log.Println("traceID:", traceID)
 }

Guidelines

1. Only store immutable, request-specific data (IDs, auth tokens).
2. Never store optional params that belong in function arguments.
3. Define unexported key types to avoid collisions across packages.

Common Pitfalls

End-to-End Example: HTTP Server with Timeouts

package main

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

func main() {
    srv := &http.Server{
        Addr:         ":8080",
        ReadTimeout:  3 * time.Second,
        WriteTimeout: 5 * time.Second,
        Handler:      http.HandlerFunc(handler),
    }

    // Shutdown gracefully on interrupt
    go func() {
        <-time.After(10 * time.Second) // Simulate interrupt
        ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
        defer cancel()
        _ = srv.Shutdown(ctx)
    }()

    fmt.Println("Serving on :8080")
    if err := srv.ListenAndServe(); err != http.ErrServerClosed {
        panic(err)
    }
    fmt.Println("Server gracefully stopped")
}

func handler(w http.ResponseWriter, r *http.Request) {
    // r.Context() inherits deadlines from the server
    select {
    case <-time.After(2 * time.Second):
        w.Write([]byte("done"))
    case <-r.Context().Done():
        http.Error(w, "request cancelled", http.StatusRequestTimeout)
    }
}

Best Practices Checklist

• Pass context.Context as the first parameter; never embed it in structs.
• Do not store contexts—pass them along the call chain.
• Cancel contexts to free resources early.
• Use short-lived timeouts close to I/O boundaries rather than a single large timeout at the root.
• Keep functions context-aware; return early on <-ctx.Done().

Conclusion

The golang context package brings order to concurrent Go programs by standardising how we propagate cancellation and deadlines. Mastering it unlocks more reliable, resource-efficient applications.

Context shows up everywhere once you start looking for it. Three follow-ups that use it heavily: graceful shutdown in Go web services, worker pools with errgroup, and a simple queue implementation. It also turns up in every LLM call you will ever write, since those are slow, cancellable and worth a deadline — see calling an LLM from Go.

Let’s write a simple program, which generates a map of numbers and print them to the console:

package main

import "log"

var numbers = make(map[int]int, 100)

func main() {
	generateNumbersMap()
}

func generateNumbersMap() {
    // Write.
	for i := 0; i < 100; i++ {
		numbers[i] = i
	}
    // Read.
	for i := 0; i < 100; i++ {
		log.Print(numbers[i])
	}
}

Now, if we run it with the data race detector option go run -race main.go, we can see the printed list of numbers in the console without any data race problems.

Everything seems to be good. Is it? Let’s add some concurrency to our super complex program 😄 and see what happens:

package main

import (
	"log"
	"sync"
)

var numbers = make(map[int]int, 100)

func main() {
	generateNumbersMap()
}

func generateNumbersMap() {
	wg := sync.WaitGroup{}
    // Write.
	for i := 0; i < 100; i++ {
		wg.Add(1)
		go func(i int) {
			defer wg.Done()
			numbers[i] = i
		}(i)
	}
    // Read.
	for i := 0; i < 100; i++ {
		wg.Add(1)
		go func(i int) {
			defer wg.Done()
			log.Print(numbers[i])
		}(i)
	}

	wg.Wait()
}

If we run it now, in the console we can notice the data race errors:

==================
WARNING: DATA RACE
Write at 0x00c0001241b0 by goroutine 8:
  runtime.mapassign_fast64()
      /usr/local/opt/go/libexec/src/runtime/map_fast64.go:92 +0x0
  main.generateNumbersMap.func1()
      /dev/webdevstation/blog-examples/concurent-map/main.go:68 +0xa4

Previous write at 0x00c0001241b0 by goroutine 7:
  runtime.mapassign_fast64()
      /usr/local/opt/go/libexec/src/runtime/map_fast64.go:92 +0x0
  main.generateNumbersMap.func1()
      /dev/webdevstation/blog-examples/concurent-map/main.go:68 +0xa4

Goroutine 8 (running) created at:
  main.generateNumbersMap()
      /dev/webdevstation/blog-examples/concurent-map/main.go:66 +0xb5
  main.main()
      /dev/webdevstation/blog-examples/concurent-map/main.go:33 +0x2f

Goroutine 7 (finished) created at:
  main.generateNumbersMap()
      /dev/webdevstation/blog-examples/concurent-map/main.go:66 +0xb5
  main.main()
      /dev/webdevstation/blog-examples/concurent-map/main.go:33 +0x2f
==================
==================
WARNING: DATA RACE
Read at 0x00c000146438 by goroutine 41:
  main.generateNumbersMap.func2()
      /dev/webdevstation/blog-examples/concurent-map/main.go:75 +0xc7

Previous write at 0x00c000146438 by goroutine 7:
  main.generateNumbersMap.func1()
      /dev/webdevstation/blog-examples/concurent-map/main.go:68 +0xb9

Goroutine 41 (running) created at:
  main.generateNumbersMap()
      /dev/webdevstation/blog-examples/concurent-map/main.go:73 +0x110
  main.main()
      /dev/webdevstation/blog-examples/concurent-map/main.go:33 +0x2f
==================

Found 2 data race(s)
exit status 66

There are several strategies that could be used to solve it. I will show one of them. We are going to introduce a new struct that provides it’s own mutex:

type SafeNumbers struct {
	sync.RWMutex
	numbers map[int]int
}

To be able to read and write items concurrently to this structure, we need to create the responsible methods:

func (sn *SafeNumbers) Add(num int) {
	sn.Lock()
	defer sn.Unlock()
	sn.numbers[num] = num
}

Here we are basically telling to lock the numbers map, during adding of the new number to it. Other goroutines will wait until it became unlocked again.

And another method for reading:

func (sn *SafeNumbers) Get(num int) (int, error) {
	sn.RLock()
	defer sn.RUnlock()
	if number, ok := sn.numbers[num]; ok {
		return number, nil
	}
	return 0, errors.New("Number does not exists")
}

Next, let’s refactor our generateNumbersMap() function:

func generateNumbersMap() {
	wg := sync.WaitGroup{}
    // Init our "safe" numbers map struct.
	safeNumbers := &SafeNumbers{
		numbers: map[int]int{},
	}
    // Write.
	for i := 0; i < 100; i++ {
		wg.Add(1)
		go func(i int) {
			defer wg.Done()
			safeNumbers.Add(i)
		}(i)
	}
    // Read.
	for i := 0; i < 100; i++ {
		wg.Add(1)
		go func(i int) {
			defer wg.Done()
			number, err := safeNumbers.Get(i)
			if err != nil {
				log.Print(err)
			} else {
				log.Print(number)
			}
		}(i)
	}

	wg.Wait()
}

If we run go run -race main.go now, there will be no more data race issues!

As I mentioned before, there also other ways to solve it. One of them is using of a special go type sync.Map.

Nevertheless, I hope this was helpful and you know now how to work safely with the maps in go. Especially, you should be careful with them when you create the web services, because every http request initiating a new goroutine.

As usual, the source code you can find here.

If the goroutines writing to that map came from a batch of work, the next thing to fix is usually how many of them there are at once — worker pools in Go with errgroup covers bounding that. And to cancel them cleanly when the request goes away, see understanding Golang context.

Ristretto is a fast, concurrent cache library built with a focus on performance and correctness.

This library was created by the Dgraph team as a contention-free cache for the Dgraph database.

Let’s dive into the practical example. We are going to build a simple application that gets a list of users from the database. In the first iteration, there will be no caching layer at all. In the second iteration, we will add a Ristretto caching and compare execution time.

Below, you can see that I defined a repository package with the Repository interface and with InMemoryRepository implementation:

package repository

import "fmt"

// Repository interface to handle users data.
type Repository interface {
	GetUsers() map[int]string
}

type InMemoryRepository struct{}

// NewInMemoryRepository constructs and returns InMemoryRepository.
func NewInMemoryRepository() *InMemoryRepository {
	return &InMemoryRepository{}
}

// GetUsers returns 50000 dummy users from the in-memory repository.
func (r *InMemoryRepository) GetUsers() map[int]string {
	users := make(map[int]string)
	for i:=1; i <= 50000; i++ {
		users[i] = fmt.Sprintf("User %d", i)
	}

	return users
}

Next, we are going to call a GetUsers() method 100 times to simulate calling of the same function from several places in the real-world applications:

package main

import (
	"fmt"
	"github.com/alexsergivan/blog-examples/ristretto/repository"
)

func main() {
	for i:=0; i<100; i ++ {
		UsersGetter(repository.NewInMemoryRepository())
	}
}

func UsersGetter(repository repository.Repository) {
	repository.GetUsers()
}

Let’s measure how much time it takes to execute it with time go run main.go:

1.46s user
0.34s system
106% cpu
1.686 total

Next, we are going to add a caching layer to our application.

Don’t forget to get the Ristretto library:

  go get github.com/dgraph-io/ristretto

Inside repository package we inject Ristretto cache:

package repository

import (
	"fmt"
	"github.com/dgraph-io/ristretto"
	"time"
)

type InMemoryRepository struct{
	cache        *ristretto.Cache
}

// NewInMemoryRepository constructs and returns InMemoryRepository.
func NewInMemoryRepository(ristrettoCache *ristretto.Cache) *InMemoryRepository {
	return &InMemoryRepository{
		cache: ristrettoCache,
	}
}

// GetUsers returns 50000 dummy users from the in-memory repository.
func (r *InMemoryRepository) GetUsers() map[int]string {
	key := "users"
	value, found := r.cache.Get(key)
    // If the users data not cached yet, get it from the repository.
	if !found {
		users := make(map[int]string)
		for i:=1; i <= 50000; i++ {
			users[i] = fmt.Sprintf("User %d", i)
		}
        // Adds data to the cache for 1h.
		r.cache.SetWithTTL(key, users, 1, 1*time.Hour)
		time.Sleep(10 * time.Millisecond)
		return users
	}
	return value.(map[int]string)
}

Next, inside the main() function we initiate a new Ristretto cache and pass it to the InMemoryRepository:

  package main

import (
	"github.com/alexsergivan/blog-examples/ristretto/repository"
	"github.com/dgraph-io/ristretto"
)

func main() {
	ristrettoCache, _ := ristretto.NewCache(&ristretto.Config{
		NumCounters: 1e7,     // Num keys to track frequency of (10M).
		MaxCost:     1 << 30, // Maximum cost of cache (1GB).
		BufferItems: 64,      // Number of keys per Get buffer.
	})

	for i:=0; i<100; i ++ {
		UsersGetter(repository.NewInMemoryRepository(ristrettoCache))
	}
}

func UsersGetter(repository repository.Repository) {
	repository.GetUsers()
}

Let’s check how much time it takes to perform the same action:

0.29s user
0.26s system
147% cpu
0.377 total

As you can notice, the total time is 4 times less than in the example without caching layer.

Despite a silly example, I hope you got an idea of how to integrate the Ristretto caching into your application and how it could improve overall performance.

The complete source code you can find here.

Ristretto is safe for concurrent use, which is exactly the problem a plain map does not solve — see concurrent map writing and reading in Go if you want the failure mode in detail. I also refactored this caching layer with generics in how Golang generics minimize the amount of code you need to write. For a cache with a very different failure mode — one that costs you money rather than latency when it silently stops working — see prompt caching.