Interface Embedding

Interface embedding in Go is a compositional mechanism that allows one interface to explicitly include the method set and type set of one or more other interfaces. When an interface is embedded, the compiler computes the intersection of the type sets and aggregates the method signatures, forming a single, unified interface definition.

type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

// ReadWriter embeds both Reader and Writer.
// Its method set contains both Read and Write.
type ReadWriter interface {
    Reader
    Writer
    Close() error // Additional explicit method
}

Mechanics and Compilation Rules

Method Set Aggregation A type satisfies the embedding interface only if it implements all methods of the embedded interfaces as well as any explicitly declared methods. In the syntax above, a concrete type must implement Read, Write, and Close to satisfy ReadWriter.

Method Overlap (Go 1.14+) Go permits embedding multiple interfaces that contain identical method signatures. The compiler merges the overlapping signatures into a single method requirement. The signatures must be strictly identical (same parameters and return types); otherwise, the compiler throws a type-checking error. Prior to Go 1.14, overlapping methods between embedded interfaces resulted in a compile-time error.

type InterfaceA interface {
    SharedMethod() string
}

type InterfaceB interface {
    SharedMethod() string
}

// Valid in Go 1.14+. The method set requires exactly one SharedMethod() string.
type MergedInterface interface {
    InterfaceA
    InterfaceB
}

Cyclic Embedding An interface cannot embed itself, either directly or indirectly through a chain of other interfaces. Attempting to do so creates a cyclic dependency, resulting in an invalid recursive type compile-time error.

// Invalid: Compile-time error
type InterfaceA interface {
    InterfaceB
}

type InterfaceB interface {
    InterfaceA
}

Embedding and Type Sets (Generics)

With the introduction of generics in Go 1.18, the definition of an interface expanded from a “method set” to a “type set”. When interfaces containing type elements (such as approximations ~ or unions |) are embedded, the resulting interface’s type set is the intersection of the embedded type sets.

This is semantically distinct from a union type element. A union (A | B) expands the allowed types, whereas embedding (A and B on separate lines) restricts the allowed types to only those present in all embedded interfaces.

type FloatAndInt interface {
    ~int | ~float32 | ~float64
}

type OnlyFloats interface {
    ~float32 | ~float64
}

// Intersection embeds FloatAndInt and OnlyFloats.
// The resulting type set is the intersection of both: ~float32 | ~float64.
type Intersection interface {
    FloatAndInt
    OnlyFloats
}

If the intersection of the embedded interfaces results in an empty type set (e.g., embedding ~int and ~float64 together), the interface cannot be satisfied by any type. Furthermore, interfaces that embed non-method elements can only be used as type constraints for generic type parameters, not as standard variable types.

Master Go with Deep Grasping Methodology!

Learn More