jit

Documentation

Overview

Package jit provides a best-effort native compilation path for CEL programs.

Index

• Variables
• func Allocate(p *Program) (map[VReg]Location, int)
• func TryEvaluate(eval NativeEvalFunc, activationType reflect.Type, input any) (bool, bool)
• type BuiltinID
  • func (b BuiltinID) String() string
• type CallerSave
• type Instr
• type Interval
• type Label
• type Location
• type NativeEvalFunc
• type NativeProgram
  • func Compile(ast *celast.AST, activationType reflect.Type) (*NativeProgram, error)
• type Opcode
  • func (op Opcode) String() string
• type Program
  • func Rewrite(prog *Program, vregLocs map[VReg]Location, spillSlots int, spillOff int) (*Program, error)
  • func Translate(ast *celast.AST, activationType reflect.Type) (*Program, error)
• type Type
  • func (t Type) String() string
• type VReg

Variables

var ErrCodegenUnsupported = errors.New("native code generation unsupported")

ErrCodegenUnsupported indicates machine-code generation is not available for translated IR.

var ErrTranslateUnsupported = errors.New("expression translation unsupported")

ErrTranslateUnsupported indicates the expression cannot be translated into JIT IR.

Functions

func Allocate

func Allocate(p *Program) (map[VReg]Location, int)

Allocate runs linear-scan allocation for the current runtime architecture. Returns the location map and the number of spill slots used.

func TryEvaluate

func TryEvaluate(eval NativeEvalFunc, activationType reflect.Type, input any) (bool, bool)

TryEvaluate checks the dynamic type against the configured activation type, extracts the underlying struct pointer, and calls the native eval function. Returns (result, true) on success, or (false, false) if the input type does not match.

Types

type BuiltinID

type BuiltinID uint16

BuiltinID identifies a pre-registered builtin helper.

const (
	BuiltinStrEq BuiltinID = iota
	BuiltinStrNe
	BuiltinStrContains
	BuiltinStrStarts
	BuiltinStrEnds
	BuiltinStrConcat
	BuiltinStrSize
	BuiltinListContainsStringSlice
	BuiltinListContainsStringArray
	BuiltinListContainsIntSlice
	BuiltinListContainsIntArray
	BuiltinListContainsUintSlice
	BuiltinListContainsUintArray
	BuiltinListContainsFloatSlice
	BuiltinListContainsFloatArray
	BuiltinListContainsBoolSlice
	BuiltinListContainsBoolArray
)

func (BuiltinID) String

func (b BuiltinID) String() string

type CallerSave

type CallerSave struct {
	Reg     int16 // Primary physical register.
	Reg2    int16 // Secondary register for string pairs (-1 if unused).
	Slot    int   // Sequential save slot index for this entry.
	IsFloat bool  // True if this is a float register (Reg >= 100).
}

CallerSave describes a physical register that must be saved/restored around a CALL_BUILTIN instruction because it is caller-saved and live across the call.

type Instr

type Instr struct {
	Op        Opcode
	Dst       VReg
	Src1      VReg
	Src2      VReg
	Imm       int64
	Lbl       Label
	Type      Type
	BuiltinID BuiltinID
}

Instr is a TAC instruction.

type Interval

type Interval struct {
	VReg  VReg
	Type  Type
	Start int
	End   int
}

Interval models the live range for a virtual register.

type Label

type Label int

Label references an instruction index after label resolution.

type Location

type Location struct {
	Reg  int16
	Reg2 int16
	Slot int
	Type Type
}

Location is the final assigned location for a VReg (register or spill slot).

type NativeEvalFunc

type NativeEvalFunc func(input unsafe.Pointer) bool

type NativeProgram

type NativeProgram struct {
	ActivationType reflect.Type
	EvalFunc       NativeEvalFunc
}

func Compile

func Compile(ast *celast.AST, activationType reflect.Type) (*NativeProgram, error)

Compile translates, allocates, and prepares a native evaluator.

type Opcode

type Opcode uint16

Opcode is the operation identifier for a TAC instruction.

const (
	OP_UNSPECIFIED Opcode = iota

	// Constants.
	CONST_INT
	CONST_UINT
	CONST_FLOAT
	CONST_BOOL
	CONST_STRING

	// Slot / type conversion.
	LOAD_FIELD
	LOAD_FIELD_SLICE
	LOAD_FIELD_ARRAY

	// Arithmetic.
	ADD_INT
	SUB_INT
	MUL_INT
	DIV_INT
	MOD_INT
	NEG_INT
	ADD_UINT
	SUB_UINT
	MUL_UINT
	DIV_UINT
	MOD_UINT
	ADD_FLOAT
	SUB_FLOAT
	MUL_FLOAT
	DIV_FLOAT
	NEG_FLOAT

	// Comparisons.
	EQ_INT
	NE_INT
	LT_INT
	LE_INT
	GT_INT
	GE_INT
	EQ_UINT
	NE_UINT
	LT_UINT
	LE_UINT
	GT_UINT
	GE_UINT
	EQ_FLOAT
	NE_FLOAT
	LT_FLOAT
	LE_FLOAT
	GT_FLOAT
	GE_FLOAT

	// Logical and misc.
	NOT
	MOVE

	// Control flow.
	LABEL
	BR
	BR_TRUE
	BR_FALSE

	// Calls and returns.
	CALL_BUILTIN
	RETURN

	// Spill reload/store (inserted by Rewrite after register allocation).
	SPILL_LOAD  // Dst = load from spill slot at byte offset Imm.
	SPILL_STORE // Src1 = store to spill slot at byte offset Imm.
)

func (Opcode) String

func (op Opcode) String() string

type Program

type Program struct {
	Instrs     []Instr
	NumVRegs   int
	StringPool []string
}

Program is the output of the translate pass.

func Rewrite

func Rewrite(
	prog *Program,
	vregLocs map[VReg]Location,
	spillSlots int,
	spillOff int,
) (*Program, error)

Rewrite rewrites the instruction stream to replace spilled vreg references with explicit SPILL_LOAD/SPILL_STORE instructions using fresh virtual registers.

For each instruction that uses a spilled vreg as a source, a SPILL_LOAD is inserted before it, loading the value from the spill slot into a fresh vreg. For each instruction that defines a spilled vreg, the destination is replaced with a fresh vreg and a SPILL_STORE is inserted after.

The fresh vregs are not assigned physical registers here; a subsequent register allocation pass handles that. Returns the rewritten instruction stream and the new NumVRegs count.

func Translate

func Translate(ast *celast.AST, activationType reflect.Type) (*Program, error)

Translate turns a checked AST into an IR program that loads variables directly from a concrete pointer-to-struct input.

Constraints:

• expression result type must be bool
• struct field types must exactly match CEL variable types
• supported scalar field kinds: int64/int, uint64/uint, float64, bool, string
• supported list membership field kinds for in_list: []string, [N]string

type Type

type Type uint8

Type is the static type associated with a virtual register value.

const (
	T_UNSPECIFIED Type = iota
	T_INT64
	T_UINT64
	T_FLOAT64
	T_BOOL
	T_STRING
)

func (Type) String

func (t Type) String() string

type VReg

type VReg uint32

VReg identifies a virtual register.