runtime

package
v2.22.1-rc.1 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2023 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
}

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.

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.