wit

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 4, 2026 License: BSD-3-Clause Imports: 7 Imported by: 0

Documentation

Overview

Package wit reads WIT (the WebAssembly Interface Types language, component-model design/mvp/WIT.md) for the subset the wasi-gfx packages use, and implements the Canonical ABI (design/mvp/CanonicalABI.md) over a core module's linear memory: alignment, sizes, flattening, loads, stores, flat lifting and lowering. A core-module host serves WIT-described imports with it, without a component-model runtime.

Index

Constants

View Source 
const (
	I32  = 'i'
	I64  = 'I'
	F32c = 'f'
	F64c = 'F'
)

Core value types, as the engine's host modules spell them.

View Source 
const (
	MaxFlatParams  = 16
	MaxFlatResults = 1
	// MaxListBytes bounds one list or string a guest passes or receives.
	MaxListBytes = 1 << 28
)

Limits of the ABI (MAX_FLAT_PARAMS, MAX_FLAT_RESULTS).

View Source 
const (
	StreamRead = iota
	StreamReadAsync
	StreamCancelRead
	StreamCancelReadAsync
	StreamDropReadable
)

Stream built-in kinds, in StreamBuiltins order.

View Source 
const (
	WaitableSetNew = iota
	WaitableSetDrop
	WaitableJoin
	WaitableSetPoll
	WaitableSetWait
)

Waitable-set built-in kinds, in WaitableBuiltins order.

View Source 
const (
	EventNone       = 0           // waitable-set.poll: nothing ready
	EventStreamRead = 2           // a stream read finished
	CopyCompleted   = 0           // payload low 4 bits
	CopyDropped     = 1           // the writer is gone
	CopyCancelled   = 2           // the read was cancelled
	Blocked         = 0xffff_ffff // an async read did not finish yet
)

Canonical ABI values of those built-ins.

View Source 
const RootModule = "$root"

RootModule is the module of the waitable-set built-ins.

Variables

View Source 
var ErrTrap = errors.New("canonical ABI trap")

ErrTrap wraps every error that the Canonical ABI defines as a trap.

View Source 
var WaitableBuiltins = []CoreImport{
	WaitableSetNew:  {"[waitable-set-new]", "", "i"},
	WaitableSetDrop: {"[waitable-set-drop]", "i", ""},
	WaitableJoin:    {"[waitable-join]", "ii", ""},
	WaitableSetPoll: {"[waitable-set-poll]", "ii", "i"},
	WaitableSetWait: {"[waitable-set-wait]", "ii", "i"},
}

WaitableBuiltins are the $root module's waitable-set built-ins.

Functions

func Align 

func Align(t *Type) uint32

Align is the type's alignment.

func Flatten 

func Flatten(t *Type) []byte

Flatten is flatten_type: the core value types of t.

func LiftFlat 

func LiftFlat(t *Type, vals []uint64, m Memory) (any, error)

LiftFlat lifts one value of type t from its core values (a function's flat result, on the caller's side).

func LiftParams 

func LiftParams(f *Func, args []uint64, m Memory) ([]any, error)

LiftParams lifts f's parameters from its core arguments (loading the parameter tuple from memory when they did not fit flat).

func Load 

func Load(m Memory, p uint32, t *Type) (any, error)

Load reads a value of type t at p (aligned).

func LowerFlat 

func LowerFlat(m Memory, a Allocator, t *Type, v any) ([]uint64, error)

LowerFlat is lower_flat: v of type t as core values.

func Parse 

func Parse(src string) (map[string]*Interface, error)

Parse reads WIT source holding one package and its interfaces.

func ParseFiles added in v0.5.0 

func ParseFiles(deps []*Interface, srcs ...string) (map[string]*Interface, error)

ParseFiles reads the files of one package (a file without a package line belongs to the package of the others), resolving uses of its own interfaces and of deps (interfaces of other packages, by short name or by ImportModule). The result is keyed by short interface name.

func ReturnsStream added in v0.6.0 

func ReturnsStream(f *Func) bool

ReturnsStream reports whether f's result is a stream (whose built-ins StreamBuiltins names).

func Size 

func Size(t *Type) uint32

Size is the type's elem_size.

func Store 

func Store(m Memory, a Allocator, p uint32, t *Type, v any) error

Store writes v of type t at p, allocating strings and lists with a.

Types

type AllocReq 

type AllocReq struct{ Align, Size uint32 }

AllocReq is one allocation a lowering needs.

type Allocator 

type Allocator interface {
	Alloc(align, size uint32) (uint32, error)
}

Allocator gives a block of guest memory (the guest's cabi_realloc).

type Case 

type Case struct {
	Name string
	Type *Type
}

Case is a variant case; Type is nil for a case without payload.

type CoreImport added in v0.6.0 

type CoreImport struct{ Name, Params, Result string }

CoreImport is a core import's name and core signature (I32 etc.).

func StreamBuiltins added in v0.6.0 

func StreamBuiltins(fn string) []CoreImport

StreamBuiltins are the built-ins for the stream that function fn (its core import name) returns, imported from fn's module; the index 0 is that stream's position among the function's streams (its only one).

type CoreSig 

type CoreSig struct {
	Params, Results []byte
	ParamsInMemory  bool
	RetPtr          bool
}

CoreSig is a function's core signature when lowered synchronously (flatten_functype, 'lower'): params beyond MaxFlatParams go through one pointer; results beyond MaxFlatResults through a return-area pointer appended to the params.

func Sig 

func Sig(f *Func) CoreSig

Sig computes f's core signature.

type Field 

type Field struct {
	Name string
	Type *Type
}

Field is a record field.

type Func 

type Func struct {
	Name   string // as in WIT: "create-buffer", or "" for a constructor
	Kind   FuncKind
	Async  bool
	Params []Param
	Result *Type // nil: no result
}

Func is a WIT function; for a method, Params[0] is "self".

func (*Func) ImportName 

func (f *Func) ImportName(resource string) string

ImportName is a function's core import name.

type FuncKind 

type FuncKind int

FuncKind says where a function is declared. 

const (
	Freestanding FuncKind = iota // "name"
	Method                       // "[method]resource.name"
	Static                       // "[static]resource.name"
	Constructor                  // "[constructor]resource"
)

Function kinds and their core import names (wit-parser's mangling).

type Interface 

type Interface struct {
	Package   string // "wasi:webgpu@0.3.0-rc.2"
	Name      string
	Types     map[string]*Type
	Resources map[string]*Resource
	Funcs     []*Func
	// contains filtered or unexported fields
}

Interface is a WIT interface: its named types, resources and functions.

func (*Interface) ImportModule 

func (i *Interface) ImportModule() string

ImportModule is the core import module name, "ns:pkg/iface@ver".

func (*Interface) ResourceNames 

func (i *Interface) ResourceNames() []string

ResourceNames lists the resources in declaration order.

type Kind 

type Kind int

Kind is a type's constructor. 

const (
	Bool Kind = iota
	U8
	U16
	U32
	U64
	S8
	S16
	S32
	S64
	F32
	F64
	Char
	String
	List
	Record
	Tuple
	Variant
	Enum
	Flags
	Option
	Result
	Own
	Borrow
	Future
	Stream
	Named // an unresolved reference, replaced by Resolve
)

Type kinds (CanonicalABI.md value types).

type Lowering 

type Lowering struct {
	Reqs []AllocReq
	// contains filtered or unexported fields
}

Lowering is a result being lowered: its allocations, then Apply.

func PlanElems added in v0.6.0 

func PlanElems(p uint32, t *Type, vs []any) (*Lowering, error)

PlanElems prepares storing vs, each a t, one after another from p (a stream read's buffer: stream.read lowers its elements there).

func PlanResult 

func PlanResult(f *Func, v any, args []uint64) (*Lowering, error)

PlanResult prepares lowering f's result v. args are the call's core arguments (the last is the return area when Sig(f).RetPtr).

func (*Lowering) Apply 

func (l *Lowering) Apply(m Memory, ptrs []uint32) (uint64, error)

Apply writes the result with the obtained pointers (one per Reqs, in order) and returns the flat result (0 when it went through memory, or when f has no result).

type Memory 

type Memory interface {
	Read(off, n uint32) ([]byte, bool)
	Write(off uint32, b []byte) bool
}

Memory is a guest's linear memory.

type Param 

type Param struct {
	Name string
	Type *Type
}

Param is a function parameter.

type Resource 

type Resource struct {
	Name  string
	Funcs []*Func
}

Resource is a resource type and its functions.

type ResultValue 

type ResultValue struct {
	Err   bool
	Value any
}

ResultValue is a result: Value is the ok or the error payload.

type Some 

type Some struct{ Value any }

Some is a present option value.

type Type 

type Type struct {
	Kind   Kind
	Name   string  // type name for named types, resource name for Own/Borrow
	Owner  string  // Own/Borrow: the resource's interface (ImportModule)
	Elem   *Type   // List, Option, Future, Stream; Result's ok
	Err    *Type   // Result's error
	Fields []Field // Record, Tuple (labels "0", "1", ...)
	Cases  []Case  // Variant
	Labels []string
}

Type is a WIT value type.

func ParamTuple 

func ParamTuple(f *Func) *Type

ParamTuple is the tuple of f's parameter types (what goes to memory when the parameters do not fit flat).

type VariantValue 

type VariantValue struct {
	Case  int
	Value any
}

VariantValue is a variant case and its payload (nil without one).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.