runtime

Documentation

Index

• Constants
• func CircuitModule() fx.Option
• type Circuit
  • func NewCircuitAndOptions(compiledComponents []CompiledComponent, policyReadAPI iface.Policy) (*Circuit, fx.Option)
  • func (circuit *Circuit) DynamicConfigUpdate(event notifiers.Event, unmarshaller config.Unmarshaller)
  • func (circuit *Circuit) Execute(tickInfo TickInfo) error
  • func (circuit *Circuit) LockExecution()
  • func (circuit *Circuit) RegisterTickEndCallback(ec TickEndCallback)
  • func (circuit *Circuit) RegisterTickStartCallback(sc TickStartCallback)
  • func (circuit *Circuit) UnlockExecution()
• type CircuitAPI
• type CircuitMetrics
• type CompiledComponent
  • func Compile(configuredComponents []ConfiguredComponent, logger *log.Logger) ([]CompiledComponent, error)
• type Component
  • func NewDummyComponent(name string) Component
• type ComponentType
• type ConfiguredComponent
• type Port
• type PortMapping
  • func PortsFromComponentConfig(componentConfig mapstruct.Object) (PortMapping, error)
• type PortToSignal
• type PortToValue
  • func (ptv PortToValue) ReadRepeatedValuePort(portName string) []Reading
  • func (ptv PortToValue) ReadSingleValuePort(portName string) Reading
• type Reading
  • func InvalidReading() Reading
  • func NewReading(value float64) Reading
• type Signal
  • func MakeConstantSignal(value float64) Signal
  • func MakeNamedSignal(name string, looped bool) Signal
• type SignalType
• type TickEndCallback
• type TickInfo
  • func NewTickInfo(timestamp, nextTimestamp time.Time, tick int, interval time.Duration) TickInfo
• type TickStartCallback

Constants

const (
	// SignalTypeNamed is a named signal.
	SignalTypeNamed = iota
	// SignalTypeConstant is a constant signal.
	SignalTypeConstant
)

Functions

func CircuitModule

func CircuitModule() fx.Option

CircuitModule returns fx options of Circuit for the main app.

Types

type Circuit

type Circuit struct {

	// Policy Read API
	iface.Policy
	// contains filtered or unexported fields
}

Circuit manages the runtime state of a set of components and their inter linkages via signals.

func NewCircuitAndOptions

func NewCircuitAndOptions(
	compiledComponents []CompiledComponent,
	policyReadAPI iface.Policy,
) (*Circuit, fx.Option)

NewCircuitAndOptions create a new Circuit struct along with fx options.

func (*Circuit) DynamicConfigUpdate

func (circuit *Circuit) DynamicConfigUpdate(event notifiers.Event, unmarshaller config.Unmarshaller)

DynamicConfigUpdate updates the circuit with the new dynamic config.

func (*Circuit) Execute

func (circuit *Circuit) Execute(tickInfo TickInfo) error

Execute runs one tick of computations of all the Components in the Circuit.

func (*Circuit) LockExecution

func (circuit *Circuit) LockExecution()

LockExecution locks the execution of the circuit.

func (*Circuit) RegisterTickEndCallback

func (circuit *Circuit) RegisterTickEndCallback(ec TickEndCallback)

RegisterTickEndCallback adds a callback function to be called when a tick ends.

func (*Circuit) RegisterTickStartCallback

func (circuit *Circuit) RegisterTickStartCallback(sc TickStartCallback)

RegisterTickStartCallback adds a callback function to be called when a tick starts.

func (*Circuit) UnlockExecution

func (circuit *Circuit) UnlockExecution()

UnlockExecution unlocks the execution of the circuit.

type CircuitAPI

type CircuitAPI interface {
	iface.Policy
	RegisterTickEndCallback(ec TickEndCallback)
	RegisterTickStartCallback(sc TickStartCallback)
	LockExecution()
	UnlockExecution()
}

CircuitAPI is for read only access to policy and also provides methods for acquiring & releasing circuit execution lock.

type CircuitMetrics

type CircuitMetrics struct {
	SignalSummaryVec *prometheus.SummaryVec
}

CircuitMetrics holds prometheus metrics related circuit.

type CompiledComponent

type CompiledComponent struct {
	Component
	InPortToSignals  PortToSignal
	OutPortToSignals PortToSignal
}

CompiledComponent consists of a Component and its In and Out ports.

This representation of component is ready to be used by a circuit.

func Compile

func Compile(
	configuredComponents []ConfiguredComponent,
	logger *log.Logger,
) ([]CompiledComponent, error)

Compile compiles list of configured components into a circuit and validates it.

type Component

type Component interface {
	Execute(inPortReadings PortToValue, tickInfo TickInfo) (outPortReadings PortToValue, err error)
	DynamicConfigUpdate(event notifiers.Event, unmarshaller config.Unmarshaller)
	// Generic name of the component, eg. "Gradient"
	Name() string
	Type() ComponentType
}

Component is the interface that all components must implement.

func NewDummyComponent

func NewDummyComponent(name string) Component

NewDummyComponent creates a standalone component which won't accept or emit any signals.

type ComponentType

type ComponentType string

ComponentType describes the type of a component based on its connectivity in the circuit.

const (
	// ComponentTypeStandAlone is a component that does not accept or emit any
	// signals.
	ComponentTypeStandAlone ComponentType = "StandAlone"
	// ComponentTypeSource is a component that emits output signal(s) but does
	// not accept an input signal.
	ComponentTypeSource ComponentType = "Source"
	// ComponentTypeSink is a component that accepts input signal(s) but does
	// not emit an output signal.
	ComponentTypeSink ComponentType = "Sink"
	// ComponentTypeSignalProcessor is a component that accepts input signal(s)
	// and emits output signal(s).
	ComponentTypeSignalProcessor ComponentType = "SignalProcessor"
)

type ConfiguredComponent

type ConfiguredComponent struct {
	Component
	// Which signals this component wants to have connected on its ports.
	PortMapping PortMapping
	// Mapstruct representation of proto config that was used to create this
	// component.  This Config is used only for observability purposes.
	//
	// Note: PortMapping is also part of Config.
	Config mapstruct.Object
}

ConfiguredComponent consists of a Component, its PortMapping and its Config.

type Port

type Port struct {
	// Note: pointers are used to detect fields being not set.
	SignalName    *string  `mapstructure:"signal_name"`
	ConstantValue *float64 `mapstructure:"constant_value"`
}

Port describes an input or output port of a component

Only one field should be set.

type PortMapping

type PortMapping struct {
	// Note: Not using policylangv1.InPort and OutPort directly to avoid
	// runtime depending on proto.
	Ins  map[string][]Port `mapstructure:"in_ports"`
	Outs map[string][]Port `mapstructure:"out_ports"`
}

PortMapping is description of a component's ports mapping.

This struct is meant to be decodable from Mapstruct representation of _any_ of the components's config. Eg. EMA component defines:

```proto

message Ins {
  InPort input = 1;
}

Ins in_ports = 1; ... ```

And such EMA component's config could be encoded and then decoded into PortMapping as:

```go

PortMapping {
  InPorts: map[string]InPort {
    "input": []InPort {{ ... }},
  },
}

```

Note how "input" is a concrete field in EMA definition, but a dynamic map key in PortMapping.

func PortsFromComponentConfig

func PortsFromComponentConfig(componentConfig mapstruct.Object) (PortMapping, error)

PortsFromComponentConfig extracts Ports from component's config.

type PortToSignal

type PortToSignal map[string][]Signal

PortToSignal is a map from port name to a slice of Signals.

type PortToValue

type PortToValue map[string][]Reading

PortToValue is a map from port name to a slice of Readings.

func (PortToValue) ReadRepeatedValuePort

func (ptv PortToValue) ReadRepeatedValuePort(portName string) []Reading

ReadRepeatedValuePort returns the reading of all the signals at port=portName. If no signal is found, []Reading{} empty list is returned.

func (PortToValue) ReadSingleValuePort

func (ptv PortToValue) ReadSingleValuePort(portName string) Reading

ReadSingleValuePort returns the reading of the first signal at port=portName. If no signal is found, InvalidReading() is returned.

type Reading

type Reading interface {
	Value() float64
	Valid() bool
}

Reading is the interface that reading implements which wraps a float Value which can be valid or invalid.

func InvalidReading

func InvalidReading() Reading

InvalidReading creates a reading with 'value' set to math.NaN(), invalid value.

func NewReading

func NewReading(value float64) Reading

NewReading creates a reading with the given value.

type Signal

type Signal struct {
	Name       string
	Value      float64
	Looped     bool
	SignalType SignalType
}

Signal represents a logical flow of Readings in a circuit and determines the linkage between Components.

func MakeConstantSignal

func MakeConstantSignal(value float64) Signal

MakeConstantSignal creates a new constant Signal.

func MakeNamedSignal

func MakeNamedSignal(name string, looped bool) Signal

MakeNamedSignal creates a new named Signal.

type SignalType

type SignalType int

SignalType enum.

type TickEndCallback

type TickEndCallback func(tickInfo TickInfo) error

TickEndCallback is a function that is called when a tick ends.

type TickInfo

type TickInfo interface {
	Timestamp() time.Time
	NextTimestamp() time.Time
	Tick() int
	Interval() time.Duration
	Serialize() *policysyncv1.TickInfo
}

TickInfo is the interface that trackInfo implements which contains information about the current tick.

func NewTickInfo

func NewTickInfo(timestamp, nextTimestamp time.Time, tick int, interval time.Duration) TickInfo

NewTickInfo returns a Tickinfo.

type TickStartCallback

type TickStartCallback func(tickInfo TickInfo) error

TickStartCallback is a function that is called when a tick starts.