runtype

Documentation

Overview

Package runtype synthesizes Go rtypes carrying interpreted-method metadata. Native code can then invoke methods on interpreter objects directly.

The mirrors here track internal/abi.Type, StructType, UncommonType, and Method byte-for-byte. Layout drift is caught by abi_test.go probes against a real native rtype.

runtype carries no method-signature/handler knowledge: Attach* take resolved stub PCs (MethodSpec). The shape pools producing those PCs live in stdlib/stubs, which imports runtype one-directionally.

Index

• Variables
• func ArrayOf(n int, elem reflect.Type) reflect.Type
• func ChanOf(dir reflect.ChanDir, elem reflect.Type) reflect.Type
• func DeriveArrayOf(n int, elem reflect.Type) reflect.Type
• func DeriveChanOf(dir reflect.ChanDir, elem reflect.Type) reflect.Type
• func DeriveMapOf(key, elem reflect.Type) reflect.Type
• func DerivePointerTo(elem reflect.Type) reflect.Type
• func DeriveSliceOf(elem reflect.Type) reflect.Type
• func FillStructLayout(reserved, realLayout reflect.Type)
• func FuncPC(fn any) uintptr
• func HasPtrToThis(t reflect.Type) bool
• func InterfaceOf(name, pkgPath string, methods []Imethod) reflect.Type
• func IsSynth(t reflect.Type) bool
• func MapOf(key, elem reflect.Type) reflect.Type
• func PointerTo(elem reflect.Type) reflect.Type
• func SliceOf(elem reflect.Type) reflect.Type
• func StampName(t reflect.Type, name string)
• func SupportedKind(k reflect.Kind) bool
• type Imethod
• type MethodSpec
• type Reservation
  • func ReserveMethods(layout reflect.Type, name, pkgPath string) (*Reservation, error)
  • func ReservePtrMethods(elem reflect.Type, name, pkgPath string) (*Reservation, error)
  • func (r *Reservation) Fill(methods []MethodSpec) error
  • func (r *Reservation) Type() reflect.Type

Variables

var ErrKindUnsupported = errors.New(
	"runtype: ReserveMethods: layout kind not supported")

ErrKindUnsupported is returned by ReserveMethods for layouts whose Kind is not in the synth catalog.

Functions

func ArrayOf

func ArrayOf(n int, elem reflect.Type) reflect.Type

ArrayOf returns the [n]elem rtype. The cloned array's Slice field is left pointing at the shadow []layoutElem; reflect.Value.Slice on a synth array therefore yields the shadow slice type, which is acceptable since the use case for these constructors is type identity, not full Value-API parity.

func ChanOf

func ChanOf(dir reflect.ChanDir, elem reflect.Type) reflect.Type

ChanOf returns the chan-elem rtype with the given direction. Channels are direct-iface single-word values regardless of elem; we clone the type-header from chan int.

func DeriveArrayOf

func DeriveArrayOf(n int, elem reflect.Type) reflect.Type

DeriveArrayOf returns [n]elem.

func DeriveChanOf

func DeriveChanOf(dir reflect.ChanDir, elem reflect.Type) reflect.Type

DeriveChanOf returns the chan-elem rtype with the given direction.

func DeriveMapOf

func DeriveMapOf(key, elem reflect.Type) reflect.Type

DeriveMapOf returns map[key]elem; synth if either component is synth.

func DerivePointerTo

func DerivePointerTo(elem reflect.Type) reflect.Type

DerivePointerTo returns *elem. For a synth elem whose PtrToThis is already wired (a reserved *T-with-methods), reflect.PointerTo returns that wired *T, so the synth and reflect sides share one *T identity; otherwise a synth elem gets a fresh synth *T and a native elem its canonical reflect.PointerTo.

func DeriveSliceOf

func DeriveSliceOf(elem reflect.Type) reflect.Type

DeriveSliceOf returns []elem.

func FillStructLayout

func FillStructLayout(reserved, realLayout reflect.Type)

FillStructLayout patches realLayout's struct layout into a reserved struct rtype in place, preserving the reservation's Str/PtrToThis (offsets 40-48), its uncommon+named flags, and its method table (past the struct header). Use it to fill a struct reserved with a provisional layout once its fields are known -- so a pointer cycle (field *T) resolves to the reserved identity.

func FuncPC

func FuncPC(fn any) uintptr

FuncPC returns the entry PC of a Go function value. A func value is a pointer to a function descriptor whose first word is the entry PC. We avoid linknaming internal/abi.FuncPCABI0 to keep the package independent of -checklinkname=0.

func HasPtrToThis

func HasPtrToThis(t reflect.Type) bool

HasPtrToThis reports whether t's PtrToThis field is wired (i.e., a ReservePtrMethods call has registered a *T-with-methods rtype reachable via reflect.PointerTo(t)). DerivePointerTo consults this to prefer reflect.PointerTo over the synth PointerTo when the wired *T exists, so the two *T identities coincide.

func InterfaceOf

func InterfaceOf(name, pkgPath string, methods []Imethod) reflect.Type

InterfaceOf builds a synthetic interface rtype whose required method set is methods, so native reflect AssignableTo/Implements resolve satisfaction against the real methods rather than a methodless any. Methods sit inline in InterfaceType.Methods (no uncommon overlay, no stub pool: an interface declares methods, it does not implement them). Each Imethod.Sig must be the canonical no-receiver func type: reflect.FuncOf and vm.FuncOf dedup via the runtime type table, so the rtype pointer the runtime compares against the concrete method's matches. An empty method set yields any; name is stamped into Str; result is anonymous.

func IsSynth

func IsSynth(t reflect.Type) bool

IsSynth reports whether t is a synth-built rtype (produced by the Reserve* or derive constructors in this package). The Derive* helpers below route between reflect.*Of (native rtype identity preserved) and the synth-safe constructors above based on this predicate.

func MapOf

func MapOf(key, elem reflect.Type) reflect.Type

MapOf returns the map[key]elem rtype.

func PointerTo

func PointerTo(elem reflect.Type) reflect.Type

PointerTo returns the *elem rtype. *T is one machine word for every elem; we clone the layout from *int.

func SliceOf

func SliceOf(elem reflect.Type) reflect.Type

SliceOf returns the []elem rtype. Slice header layout (Size 24, one pointer at offset 0) is independent of elem; we clone from []int.

func StampName

func StampName(t reflect.Type, name string)

StampName overwrites t's type name in place: registers name via addReflectOff, points Str at it, sets tflagNamed, and clears tflagExtraStar. Layout is untouched (a type name is a label, not structure), so t's identity, fields, methods, and any derived types stay valid. This is the safest possible synth mutation. CALLER CONTRACT: t must be a heap rtype mvm owns (e.g. a reflect.StructOf placeholder). Stamping a shared canonical rtype (int, a native struct like time.Time) would corrupt the name of every value of that type process-wide.

func SupportedKind

func SupportedKind(k reflect.Kind) bool

SupportedKind reports whether a layout of kind k can be given a reserved method-bearing identity -- the single source of truth for the reservable-kind catalog, matching ReserveMethods' dispatch (a named primitive, struct, slice, array, map, or func).

Types

type Imethod

type Imethod struct {
	Name     string
	Exported bool
	Sig      reflect.Type
}

Imethod is one interface method: name, export status, and no-receiver signature (e.g. func() bool for Timeout).

type MethodSpec

type MethodSpec struct {
	Name     string
	Exported bool
	Sig      reflect.Type
	StubPC   uintptr
}

MethodSpec describes one method to install on a synthesized rtype. StubPC is the dispatch-stub entry PC wired into the method's Ifn/Tfn; the caller resolves it from the method's signature shape before Fill.

type Reservation

type Reservation struct {
	// contains filtered or unexported fields
}

Reservation is a synth rtype whose method table has room allocated but is initially empty (Mcount 0). Fill installs the methods in place, preserving the rtype's identity, so a container that captured the reserved rtype before Fill observes the methods afterward (the basis for cascade-free materialize-once).

func ReserveMethods

func ReserveMethods(layout reflect.Type, name, pkgPath string) (*Reservation, error)

ReserveMethods reserves a method-bearing identity for layout (dispatching by kind) without yet installing any method. Fill the returned Reservation once the method stubs are known.

func ReservePtrMethods

func ReservePtrMethods(elem reflect.Type, name, pkgPath string) (*Reservation, error)

ReservePtrMethods reserves a *T identity carrying eventual ptr-receiver methods and wires elem.PtrToThis so reflect.PointerTo(elem) returns it, all before Fill.

func (*Reservation) Fill

func (r *Reservation) Fill(methods []MethodSpec) error

Fill installs methods into the reserved method table in place, publishing the counts last so a reader seeing them also sees written slots; the caller must establish happens-before to other goroutines (attach runs before the VM resumes). len(methods) must be in [1, maxMethods].

func (*Reservation) Type

func (r *Reservation) Type() reflect.Type

Type returns the reserved rtype. It is a valid named type with zero methods until Fill runs.