runtime

package
v2.29.4-rc.1 Latest Latest
Warning

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

Go to latest
Published: Jan 4, 2024 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// NestedComponentDelimiter is the delimiter used to separate the parent circuit ID and the nested circuit ID.
	NestedComponentDelimiter = "."
	// RootComponentID is the ID of the root component.
	RootComponentID = "root"
)
View Source
const (
	// SignalTypeNamed is a named signal.
	SignalTypeNamed = iota
	// SignalTypeConstant is a constant signal.
	SignalTypeConstant
)

Variables

This section is empty.

Functions

func BackgroundSchedulerModule added in v2.15.0

func BackgroundSchedulerModule() fx.Option

BackgroundSchedulerModule returns fx options for Background Jobs in the main app.

func BackgroundSchedulerModuleForPolicyApp added in v2.15.0

func BackgroundSchedulerModuleForPolicyApp(circuitAPI CircuitSuperAPI) fx.Option

BackgroundSchedulerModuleForPolicyApp returns fx options for Scheduler in the policy app. Invoked only once per policy.

func CircuitModule

func CircuitModule() fx.Option

CircuitModule returns fx options of Circuit for the main app.

func Compile

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

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

Types

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

func NewCircuitAndOptions(
	configuredComponents []*ConfiguredComponent,
	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) GetTickInfo added in v2.15.0

func (circuit *Circuit) GetTickInfo() TickInfo

GetTickInfo returns the current tick info.

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) ScheduleConditionalBackgroundJob added in v2.15.0

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

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. Warning: This method should only be called by the Components during a tick execution.

func (*Circuit) UnlockExecution

func (circuit *Circuit) UnlockExecution()

UnlockExecution unlocks the execution of the circuit.

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

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

NewDummyComponent creates a component with provided name and type.

type ComponentID

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

ComponentID is a unique identifier for a component.

func NewComponentID

func NewComponentID(id string) ComponentID

NewComponentID creates a new 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 added in v2.11.0

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

NewConfiguredComponent creates a new ConfiguredComponent.

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

func ConstantSignalFromProto(constantSignalProto *policylangv1.ConstantSignal) *ConstantSignal

ConstantSignalFromProto creates a ConstantSignal from a proto message.

func (*ConstantSignal) Description

func (constantSignal *ConstantSignal) Description() string

Description returns a description of the constant signal.

func (*ConstantSignal) Float

func (constantSignal *ConstantSignal) Float() float64

Float returns the float value of the constant signal.

func (*ConstantSignal) IsSpecial

func (constantSignal *ConstantSignal) IsSpecial() bool

IsSpecial returns true if the constant signal is a special value.

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

func NewPortMapping() PortMapping

NewPortMapping creates a new PortMapping.

func PortsFromComponentConfig

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

PortsFromComponentConfig extracts Ports from component's config.

func (*PortMapping) AddInPort

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

AddInPort adds an input port to the PortMapping.

func (*PortMapping) AddOutPort

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

AddOutPort adds an output port to the PortMapping.

func (*PortMapping) GetInPort

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

GetInPort returns true if the port exists in the PortMapping.

func (*PortMapping) GetOutPort

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

GetOutPort returns true if the port exists in the PortMapping.

func (*PortMapping) Merge

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

Merge merges two PortMappings.

type PortToReading

type PortToReading map[string][]Reading

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

func (PortToReading) ReadRepeatedReadingPort

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

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

func (PortToReading) ReadSingleReadingPort

func (ptr PortToReading) ReadSingleReadingPort(portName string) Reading

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

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

func InvalidReading() Reading

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

func NewBoolReading

func NewBoolReading(value bool) Reading

NewBoolReading creates a reading with the given bool value.

func NewReading

func NewReading(value float64) Reading

NewReading creates a reading with the given float64 value.

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 (*Signal) ConstantSignalValue

func (s *Signal) ConstantSignalValue() float64

ConstantSignalValue returns the value of the constant signal.

func (*Signal) SignalID

func (s *Signal) SignalID() SignalID

SignalID returns the Signal ID.

func (*Signal) SignalType

func (s *Signal) SignalType() SignalType

SignalType returns the Signal type of the port.

type SignalID

type SignalID struct {
	SubCircuitID string
	SignalName   string
}

SignalID is a unique identifier for a signal.

func MakeRootSignalID

func MakeRootSignalID(signalName string) SignalID

MakeRootSignalID creates SignalID with "root" SubCircuitID.

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

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

NewTickInfo returns a Tickinfo.

type TickStartCallback

type TickStartCallback func(circuit CircuitAPI) error

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

Directories

Path Synopsis
tristate is a helper package for tri-state boolean logic, which is used for logical combinator components.
tristate is a helper package for tri-state boolean logic, which is used for logical combinator components.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL