runtime

package
v0.41.0 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	StdinFileHandleID  int64 = 0
	StdoutFileHandleID int64 = 1
	StderrFileHandleID int64 = 2
)

Stdio file handle IDs mirror the conventional process file descriptors.

Variables

This section is empty.

Functions

func Call added in v0.33.0 

func Call(ctx context.Context, prog Program, registry map[string]FuncCreator, input messages.Msg) (messages.Msg, int, error)

Call runs a single request-response round-trip using program Start/Stop. It sends the provided input to Start, waits for one message on Stop, then cancels and waits for all handlers to finish.

func Run added in v0.26.0 

func Run(ctx context.Context, prog Program, registry map[string]FuncCreator) (int, error)

func Terminate added in v0.37.0 

func Terminate(ctx context.Context, exitCode int)

Terminate requests graceful runtime termination with the provided process exit code.

func Uint8Index added in v0.34.0 

func Uint8Index(idx int) uint8

Uint8Index validates idx and returns it as uint8 or panics.

It is exported because native runtime functions live in a child package.

Types

type ArrayInport added in v0.25.0 

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

func NewArrayInport added in v0.25.0 

func NewArrayInport(
	tracer *Tracer,
	chans []<-chan OrderedMsg,
	addr PortAddr,
	interceptor Interceptor,
) *ArrayInport

func (ArrayInport) Len added in v0.25.0 

func (a ArrayInport) Len() int

func (*ArrayInport) Receive added in v0.25.0 

func (a *ArrayInport) Receive(ctx context.Context, idx int) (OrderedMsg, bool)

Receive receives a message from a specific array slot together with its runtime ordering metadata.

func (*ArrayInport) ReceiveAll added in v0.26.0 

func (a *ArrayInport) ReceiveAll(ctx context.Context, f func(idx int, ordered OrderedMsg) bool) bool

ReceiveAll receives messages from all available array inport slots just once. It returns false if context is done or if the provided function returns false. The function is called for each message received. The function should return false if it wants to stop receiving messages. Functions receive full transport envelopes and are called in order of incoming messages, not in order of slots.

func (*ArrayInport) Select added in v0.26.0 

func (a *ArrayInport) Select(ctx context.Context) (SelectedMsg, bool)

Select returns oldest available message across all available array inport slots.

type ArrayOutport added in v0.25.0 

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

func NewArrayOutport added in v0.25.0 

func NewArrayOutport(tracer *Tracer, addr PortAddr, interceptor Interceptor, slots []chan<- OrderedMsg) *ArrayOutport

func (*ArrayOutport) Len added in v0.25.0 

func (a *ArrayOutport) Len() int

func (*ArrayOutport) Send added in v0.25.0 

func (a *ArrayOutport) Send(ctx context.Context, idx uint8, msg messages.Msg, causes ...OrderedMsg) bool

func (*ArrayOutport) SendAll added in v0.25.0 

func (a *ArrayOutport) SendAll(ctx context.Context, msg messages.Msg, causes ...OrderedMsg) bool

SendAllV2 sends the same message to all slots of the array outport. It returns false if context is done. It blocks until message is sent to all slots. Slots are not guaranteed to be handled in order, message is sent to first available slot. Each slot is guaranteed to be handled only once. TODO: figure out why this is the only working version of `SendAll`

type FileHandles added in v0.39.0 

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

FileHandles owns process files that Neva code addresses through opaque IDs.

The generated Go runtime keeps one FileHandles table in the stdlib registry and shares it between all file-related extern functions. The table only protects handle lookup and lifecycle bookkeeping; actual file I/O happens on the returned *os.File after Get releases the lock.

This intentionally starts with one simple table instead of sharding. Get uses a read lock, so concurrent reads/writes through already-open handles do not block each other at the table level. Add and Close take the write lock because they mutate the map and the next dynamic ID. If open/close churn becomes a measured bottleneck, sharding can be added inside this type without changing the public runtime API.

func NewFileHandles added in v0.39.0 

func NewFileHandles() *FileHandles

NewFileHandles creates a runtime file-handle table with process stdio handles.

func (*FileHandles) Add added in v0.39.0 

func (handles *FileHandles) Add(file *os.File) int64

Add stores file and returns a new opaque runtime handle ID.

The caller transfers lifecycle ownership to FileHandles. User code must close the returned ID through the file_close extern when it is done with the file.

func (*FileHandles) Close added in v0.39.0 

func (handles *FileHandles) Close(handleID int64) error

Close removes and closes a dynamic file handle.

Close is intentionally not idempotent. A second close of the same dynamic ID reports an unknown handle, matching Go's own "use after close is an error" posture and making double-close bugs visible to Neva code through the err outport. Stdio handles also return an error because their lifetime belongs to the host process, not to the Neva program.

func (*FileHandles) Get added in v0.39.0 

func (handles *FileHandles) Get(handleID int64) (*os.File, error)

Get returns the file registered for handleID.

The returned *os.File remains owned by FileHandles; callers may perform I/O on it but must not close it directly. The lookup lock is released before return, so long reads or writes do not hold the table lock.

type FuncCall 

type FuncCall struct {
	Config messages.Msg
	IO     IO
	Ref    string
}

type FuncCreator 

type FuncCreator interface {
	Create(IO, messages.Msg) (func(context.Context), error)
}

type IO added in v0.26.0 

type IO struct {
	In  Inports
	Out Outports
}

type Inport added in v0.26.0 

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

func NewInport added in v0.26.0 

func NewInport(
	array *ArrayInport,
	single *SingleInport,
) Inport

func (Inport) Array added in v0.26.0 

func (f Inport) Array() *ArrayInport

func (Inport) Single added in v0.26.0 

func (f Inport) Single() *SingleInport

type Inports added in v0.26.0 

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

func NewInports added in v0.26.0 

func NewInports(ports map[string]Inport) Inports

func (Inports) Array added in v0.26.0 

func (f Inports) Array(name string) (ArrayInport, error)

func (Inports) Ports added in v0.26.0 

func (f Inports) Ports() map[string]Inport

func (Inports) Single added in v0.26.0 

func (f Inports) Single(name string) (SingleInport, error)

type Interceptor added in v0.25.0 

type Interceptor interface {
	Sent(context.Context, PortSlotAddr, OrderedMsg, TraceHop)
	Received(context.Context, PortSlotAddr, OrderedMsg) OrderedMsg
}

func NewInterceptor added in v0.37.0 

func NewInterceptor(tracePath, comment string) (Interceptor, func() error, error)

NewInterceptor always enables in-memory tracing. When tracePath is empty, it skips JSONL emission and returns the production interceptor.

type JSONLTraceFileWriter added in v0.37.0 

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

JSONLTraceFileWriter is an interceptor that writes each tracing event into a file in a JSONL format.

func NewDebugInterceptor added in v0.26.0 

func NewDebugInterceptor(comment string) *JSONLTraceFileWriter

func (*JSONLTraceFileWriter) Open added in v0.37.0 

func (d *JSONLTraceFileWriter) Open(filepath string) (func() error, error)

Open safely opens the file for writing and returns its close func.

func (*JSONLTraceFileWriter) Received added in v0.37.0 

func (d *JSONLTraceFileWriter) Received(_ context.Context, receiver PortSlotAddr, ordered OrderedMsg) OrderedMsg

Received implements Interceptor interface. The only thing this interceptor really does - is writes JSONL line to a file.

func (*JSONLTraceFileWriter) Sent added in v0.37.0 

func (d *JSONLTraceFileWriter) Sent(
	_ context.Context,
	sender PortSlotAddr,
	ordered OrderedMsg,
	hop TraceHop,
)

Sent implements Interceptor interface. The only thing this interceptor really does - is writes JSONL line to a file.

type NoEffectInterceptor added in v0.37.0 

type NoEffectInterceptor struct{}

NoEffectInterceptor exist to be used as default interceptor when no actual interception is needed. Just to satisfy compiler.

func (NoEffectInterceptor) Prepare added in v0.37.0 

func (NoEffectInterceptor) Prepare() error

func (NoEffectInterceptor) Received added in v0.37.0 

func (p NoEffectInterceptor) Received(_ context.Context, _ PortSlotAddr, ordered OrderedMsg) OrderedMsg

func (NoEffectInterceptor) Sent added in v0.37.0 

func (p NoEffectInterceptor) Sent(
	_ context.Context,
	_ PortSlotAddr,
	ordered OrderedMsg,
	_ TraceHop,
)

type OrderedMsg added in v0.26.0 

type OrderedMsg struct {
	messages.Msg
	// contains filtered or unexported fields
}

OrderedMsg is a transport envelope with payload and runtime ordering metadata.

func (OrderedMsg) String added in v0.26.0 

func (o OrderedMsg) String() string

String formats the payload without exposing transport metadata.

type Outport added in v0.26.0 

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

func NewOutport added in v0.26.0 

func NewOutport(
	single *SingleOutport,
	array *ArrayOutport,
) Outport

type Outports added in v0.26.0 

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

func NewOutports added in v0.26.0 

func NewOutports(ports map[string]Outport) Outports

func (Outports) Array added in v0.26.0 

func (f Outports) Array(name string) (ArrayOutport, error)

func (Outports) Single added in v0.26.0 

func (f Outports) Single(name string) (SingleOutport, error)

type PortAddr 

type PortAddr struct {
	Path string `json:"Path"`
	Port string `json:"Port"`
}

type PortSlotAddr added in v0.26.0 

type PortSlotAddr struct {
	Index *uint8 `json:",omitempty"` // nil means single port
	PortAddr
}

type Program 

type Program struct {
	// for programmer start is inport and stop is outport, but for runtime it's inverted
	Start     *SingleOutport // Start must be inport of the first function
	Stop      *SingleInport  // Stop must be outport of the (one of the) terminator function(s)
	FuncCalls []FuncCall
}

type SelectedMsg added in v0.26.0 

type SelectedMsg struct {
	OrderedMsg OrderedMsg
	SlotIdx    uint8
}

SelectedMsg is a message selected from available messages on all array inport slots.

func (SelectedMsg) String added in v0.26.0 

func (s SelectedMsg) String() string

type SingleInport added in v0.25.0 

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

func NewSingleInport added in v0.25.0 

func NewSingleInport(
	tracer *Tracer,
	ch <-chan OrderedMsg,
	addr PortAddr,
	interceptor Interceptor,
) *SingleInport

func (SingleInport) Receive added in v0.25.0 

func (s SingleInport) Receive(ctx context.Context) (OrderedMsg, bool)

Receive returns the next incoming transport envelope with its runtime ordering metadata.

type SingleOutport added in v0.25.0 

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

func NewSingleOutport added in v0.25.0 

func NewSingleOutport(
	tracer *Tracer,
	addr PortAddr,
	interceptor Interceptor,
	outCh chan<- OrderedMsg,
) *SingleOutport

func (SingleOutport) Send added in v0.25.0 

func (s SingleOutport) Send(ctx context.Context, msg messages.Msg, causes ...OrderedMsg) bool

type TraceHop added in v0.37.0 

type TraceHop struct {
	Sender   *PortSlotAddr
	Receiver *PortSlotAddr
	Message  string
	// CauseIndexes is the single source of truth for causal edges in traceStore.
	// Tree views are reconstructed from these indexes on demand.
	CauseIndexes []uint64
	// Index is materialized on read from traceStore map key.
	// We do not persist it in storage separately to avoid duplicated state.
	Index uint64
}

type Tracer added in v0.37.0 

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

func NewTracer added in v0.37.0 

func NewTracer() *Tracer

func TracerFromIO added in v0.37.0 

func TracerFromIO(runtimeIO IO) *Tracer

TracerFromIO returns the runtime tracer bound to this IO wiring.

This is a pragmatic bridge used by runtime funcs (for example runtime.Panic) to read the current dataflow trace from runtime state. It is intentionally wiring-based in the current implementation and may be redesigned later.

func (*Tracer) HopByOrderedMsg added in v0.37.0 

func (t *Tracer) HopByOrderedMsg(ordered OrderedMsg) (TraceHop, bool)

HopByOrderedMsg returns a normalized hop for a concrete ordered message.

func (*Tracer) HopsByCauseIndexes added in v0.37.0 

func (t *Tracer) HopsByCauseIndexes(causeIndexes []uint64) []TraceHop

HopsByCauseIndexes resolves parent hops by stored cause indexes. Missing indexes are ignored to keep trace-read path resilient.

Source Files

View all Source files

Directories

Path Synopsis
Package funcs implements low-level flows (runtime functions).
 Package funcs implements low-level flows (runtime functions).
Package messages defines immutable Neva values and pure operations over them.
 Package messages defines immutable Neva values and pure operations over them.

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.