runtime

type BackgroundJob ¶ added in v2.15.0

type BackgroundJob interface {
	GetJob() jobs.Job
	NotifyCompletion()
}

BackgroundJob is an interface that must be implemented by background jobs to get scheduled as a background job in the Circuit.

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(
	configuredComponents []*ConfiguredComponent,
	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) GetTickInfo() TickInfo

func (circuit *Circuit) LockExecution()

func (circuit *Circuit) RegisterTickEndCallback(ec TickEndCallback)

func (circuit *Circuit) RegisterTickStartCallback(sc TickStartCallback)

func (circuit *Circuit) ScheduleConditionalBackgroundJob(job BackgroundJob, ticksPerExecution int)

func (circuit *Circuit) UnlockExecution()

type CircuitAPI ¶

type CircuitAPI interface {
	iface.Policy
	// ScheduleConditionalBackgroundJob schedules a background job for one time execution. The job gets scheduled only if currentTick is a multiple of ticksPerExecution. There can be at most a single job with a certain name pending to be run at a time. Subsequent invocations with the same job name overwrite the previous one.
	ScheduleConditionalBackgroundJob(backgroundJob BackgroundJob, ticksPerExecution int)
	GetTickInfo() TickInfo
}

CircuitAPI is for read only access to policy and scheduling of background jobs.

type CircuitMetrics ¶

type CircuitMetrics struct {
	SignalSummaryVec            *prometheus.SummaryVec
	InvalidSignalReadingsTotal  *prometheus.CounterVec
	InfiniteSignalReadingsTotal *prometheus.CounterVec
}

CircuitMetrics holds prometheus metrics related circuit.

type CircuitSuperAPI ¶ added in v2.15.0

type CircuitSuperAPI interface {
	CircuitAPI
	RegisterTickEndCallback(ec TickEndCallback)
	RegisterTickStartCallback(sc TickStartCallback)
	LockExecution()
	UnlockExecution()
}

CircuitSuperAPI is for read only access to policy, scheduling of background jobs and also provides methods for acquiring & releasing circuit execution lock.

type Component ¶

type Component interface {
	Execute(inPortReadings PortToReading, circuitAPI CircuitAPI) (outPortReadings PortToReading, err error)
	DynamicConfigUpdate(event notifiers.Event, unmarshaller config.Unmarshaller)
	// Generic name of the component, eg. "Gradient"
	Name() string
	Type() ComponentType
	// ShortDescription is used when generating mermaid or dot diagrams.
	ShortDescription() string
	// IsActuator returns true if the component is an actuator.
	IsActuator() bool
}

Component is the interface that all components must implement.

func NewDummyComponent(name, shortDescription string, componentType ComponentType) Component

type ComponentID ¶

type ComponentID interface {
	String() string
	ChildID(id string) ComponentID
	ParentID() (ComponentID, bool)
}

ComponentID is a unique identifier for a component.

func NewComponentID(id string) ComponentID

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 utils.MapStruct
	// ComponentID is the unique ID of this component within the circuit.
	ComponentID ComponentID
}

ConfiguredComponent consists of a Component and its PortMapping.

func NewConfiguredComponent(
	component Component,
	config any,
	componentID ComponentID,
	doParsePortMapping bool,
) (*ConfiguredComponent, error)

type ConstantSignal ¶

type ConstantSignal struct {
	SpecialValue string  `mapstructure:"special_value"`
	Value        float64 `mapstructure:"value"`
}

ConstantSignal is a mirror struct to same proto message.

func ConstantSignalFromProto(constantSignalProto *policylangv1.ConstantSignal) *ConstantSignal

func (constantSignal *ConstantSignal) Description() string

func (constantSignal *ConstantSignal) Float() float64

func (constantSignal *ConstantSignal) IsSpecial() bool

type PortMapping ¶

type PortMapping struct {
	// Note: Not using policylangv1.InPort and OutPort directly to avoid
	// runtime depending on proto.
	Ins  PortToSignals `mapstructure:"in_ports"`
	Outs PortToSignals `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 NewPortMapping() PortMapping

func PortsFromComponentConfig(componentConfig utils.MapStruct, subCircuitID string) (PortMapping, error)

func (p *PortMapping) AddInPort(portName string, signals []Signal)

func (p *PortMapping) AddOutPort(portName string, signals []Signal)

func (p *PortMapping) GetInPort(portName string) ([]Signal, bool)

func (p *PortMapping) GetOutPort(portName string) ([]Signal, bool)

func (p *PortMapping) Merge(other PortMapping) error

type PortToReading ¶

type PortToReading map[string][]Reading

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

func (ptr PortToReading) ReadRepeatedReadingPort(portName string) []Reading

func (ptr PortToReading) ReadSingleReadingPort(portName string) Reading

type PortToSignals ¶

type PortToSignals map[string][]Signal

PortToSignals is a map from port name to a list of signals.

type Reading ¶

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

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

func InvalidReading() Reading

func NewBoolReading(value bool) Reading

func NewReading(value float64) Reading

type Signal ¶

type Signal struct {
	SubCircuitID   string
	SignalName     string         `mapstructure:"signal_name"`
	ConstantSignal ConstantSignal `mapstructure:"constant_signal"`
	Looped         bool
}

Signal describes an input or output port of a component

Only one field should be set.

func (s *Signal) ConstantSignalValue() float64

func (s *Signal) SignalID() SignalID

func (s *Signal) SignalType() SignalType

type SignalID ¶

type SignalID struct {
	SubCircuitID string
	SignalName   string
}

SignalID is a unique identifier for a signal.

func MakeRootSignalID(signalName string) SignalID

type SignalType ¶

type SignalType int

SignalType enum.

type TickEndCallback ¶

type TickEndCallback func(circuit CircuitAPI) error

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

type TickInfo ¶

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

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

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

type TickStartCallback ¶

type TickStartCallback func(circuit CircuitAPI) error

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