Type parameters and constraints: type sets, inference limits, and GCShape stenciling

Constraints are type sets, not class hierarchies

A type parameter list — func Sum[T Number](xs []T) T — introduces T as a placeholder that must satisfy its constraint. A constraint is an ordinary interface, but used in a new role: instead of describing what a value can do, it describes the set of types allowed. Inside that interface you can list types directly, join them with | into unions, and prefix them with ~ to mean “any type whose underlying type is this”:

// A constraint is an interface used as a type set.
type Number interface {
	~int | ~int64 | ~float64 // ~T: any type whose underlying type is T
}

func Sum[T Number](xs []T) T {
	var total T
	for _, x := range xs {
		total += x // legal: every type in the set supports +
	}
	return total
}

type Celsius float64 // named type, underlying type float64

var _ = Sum([]Celsius{20.5, 21.0}) // compiles only because of the ~

The ~ matters more than it looks. Go code is full of named types — type UserID int64, type Port int — and a constraint written as a bare int64 admits only int64, not UserID. Without the tilde your “numeric” library rejects half the codebase’s domain types, and the failure is a compile error at the caller, far from the constraint that caused it. The rule of thumb: in reusable constraints, always write ~T unless you have a specific reason to exclude named types. Two more pieces complete the vocabulary: comparable is a predeclared constraint meaning “supports == and !=” (it is what map keys need, and it cannot be expressed as a union — the set is infinite), and constraints can also carry methods, in which case a type must both be in the set and have the methods. What a constraint can never do is act as an ordinary type: you cannot declare var n Number — type sets exist only at instantiation time.

Inference: powerful at call sites, absent everywhere else

Before you rely on inference to keep call sites clean, it helps to know where it simply stops — so you can spot the design smell before a teammate trips over it.

Type inference is what makes generics readable: Sum(prices) instead of Sum[Celsius](prices). The compiler infers type arguments from the types of the function arguments, then checks them against the constraints. But inference has hard edges, and senior code review means knowing where they are:

func Map[T, U any](xs []T, f func(T) U) []U { /* ... */ }

ys := Map(ids, strconv.Itoa) // T=int, U=string — inferred from arguments

func Zero[T any]() T { var z T; return z }

v := Zero[int]() // explicit instantiation required:
                 // T appears only in the result, inference has no input to look at

A type parameter that appears only in return position can never be inferred — there is no argument carrying the information. Untyped constants are the second trap: passing 1 to a [T Number] parameter infers int (the constant’s default type), not int64, and if the constraint excludes int the call fails even though 1 is a perfectly valid int64. The third limit is structural: inference works at call sites only. There is no inference from assignment context, no partial specialization, no overloading on constraints. When inference fails, the fix is mechanical — write the type argument explicitly — but an API that routinely forces callers to write F[concrete](...) is a design smell worth fixing by moving a type parameter into an argument.

Instantiation: GCShape stenciling, honestly

What happens when you actually call Sum[Celsius]? C++ would monomorphize: emit fresh machine code for every type argument — fast code, slow compiles, big binaries. Java erases: one copy of the code, everything boxed. Go 1.18 chose a midpoint called GCShape stenciling with dictionaries. The compiler groups type arguments by GC shape: two types share a shape if they look identical to the memory allocator and garbage collector — same size, same pointer layout. int64, time.Duration, and Celsius-over-float64 are different shapes (well, int64 and Duration share one); but the big collapse is this: every pointer type is one shape. *User, *Order, *bytes.Buffer — one shared instantiation. To tell them apart at runtime, the compiler passes a hidden dictionary argument holding the concrete type’s metadata: its runtime._type, its method addresses, derived types. Code that calls a method on the type parameter loads the address from the dictionary and calls indirectly — which also means no inlining across that call.

The honest performance consequences: value-type instantiations get dedicated code, direct calls, full inlining — real wins over interface{} versions that had to box and assert. Pointer-type instantiations get shared code and dictionary-indirect calls — roughly the cost profile of an interface method call, sometimes a touch worse because the dictionary adds a load. That is exactly the seam the Hook’s team hit: Cache[string, int64] monomorphized; Cache[string, *Session] went through the dictionary. Stenciling is an implementation detail the spec does not promise — gc’s strategy has stayed shape-based since 1.18 — but designing APIs as if generics were free monomorphization is how benchmark surprises get into production reviews.