directive

package
v0.20.8 Latest Latest
Warning

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

 Go to latest Published: Dec 29, 2022 License: MIT Imports: 13 Imported by: 42

Documentation

Overview

Package directive declares the Directive type. The Directive is an instruction to all controllers attached to a bus indicating desired state. Directives are de-duplicated in the controller. Each directive is added with a listener, which receives events with links matching the directive.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidLength        = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflow          = fmt.Errorf("proto: integer overflow")
	ErrUnexpectedEndOfGroup = fmt.Errorf("proto: unexpected end of group")
)
View Source 
var File_github_com_aperturerobotics_controllerbus_directive_directive_proto protoreflect.FileDescriptor

Functions

This section is empty.

Types

type AttachedValue 

type AttachedValue interface {
	// GetValueID returns the value ID.
	GetValueID() uint32
	// GetValue returns the value.
	GetValue() Value
}

AttachedValue is a value with some metadata.

type Controller 

type Controller interface {
	// GetDirectives returns a list of all currently executing directives.
	GetDirectives() []Instance

	// AddDirective adds a directive to the controller.
	// This call de-duplicates equivalent directives.
	//
	// cb receives values in order as they are emitted.
	// cb can be nil.
	// cb should not block.
	//
	// Returns the instance, new reference, and any error.
	AddDirective(Directive, ReferenceHandler) (Instance, Reference, error)

	// AddHandler adds a directive handler.
	// The handler will receive calls for all existing directives (initial set).
	// An error is returned only if adding the handler failed.
	// Returns a function to remove the handler.
	// The release function must be non-nil if err is nil, and nil if err != nil.
	AddHandler(handler Handler) (func(), error)
}

Controller manages running directives and handlers.

type DebugValues 

type DebugValues map[string][]string

DebugValues maps string key to a list of values. It is used for debug visualizations.

func NewDebugValues 

func NewDebugValues() DebugValues

NewDebugValues constructs a new DebugValues.

type Debuggable 

type Debuggable interface {
	// GetDebugVals returns the directive arguments as key/value pairs.
	// This should be something like param1="test", param2="test".
	// This is not necessarily unique, and is primarily intended for display.
	GetDebugVals() DebugValues
}

Debuggable indicates the directive implements the DebugVals interface.

type Directive 

type Directive interface {
	// Validate validates the directive.
	// This is a cursory validation to see if the values "look correct."
	Validate() error

	// GetValueOptions returns options relating to value handling.
	GetValueOptions() ValueOptions

	// GetName returns the directives type name (i.e. DoSomething).
	// This is not intended to be unique and is primarily used for display.
	GetName() string
}

Directive implements a requested state (with a set of values).

type DirectiveInfo 

type DirectiveInfo struct {

	// Name is the directive name.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// DebugVals contains the directive debug values.
	DebugVals []*ProtoDebugValue `protobuf:"bytes,2,rep,name=debug_vals,json=debugVals,proto3" json:"debug_vals,omitempty"`
	// contains filtered or unexported fields
}

DirectiveInfo contains directive information in protobuf form.

func NewDirectiveInfo 

func NewDirectiveInfo(dir Directive) *DirectiveInfo

NewDirectiveInfo constructs a new DirectiveInfo from a directive.

func (*DirectiveInfo) CloneGenericVT added in v0.12.3 

func (m *DirectiveInfo) CloneGenericVT() proto.Message

func (*DirectiveInfo) CloneVT added in v0.12.3 

func (m *DirectiveInfo) CloneVT() *DirectiveInfo

func (*DirectiveInfo) Descriptor deprecated 

func (*DirectiveInfo) Descriptor() ([]byte, []int)

Deprecated: Use DirectiveInfo.ProtoReflect.Descriptor instead.

func (*DirectiveInfo) EqualVT added in v0.10.0 

func (this *DirectiveInfo) EqualVT(that *DirectiveInfo) bool

func (*DirectiveInfo) GetDebugVals 

func (x *DirectiveInfo) GetDebugVals() []*ProtoDebugValue

func (*DirectiveInfo) GetName 

func (x *DirectiveInfo) GetName() string

func (*DirectiveInfo) MarshalToSizedBufferVT added in v0.10.0 

func (m *DirectiveInfo) MarshalToSizedBufferVT(dAtA []byte) (int, error)

func (*DirectiveInfo) MarshalToVT added in v0.10.0 

func (m *DirectiveInfo) MarshalToVT(dAtA []byte) (int, error)

func (*DirectiveInfo) MarshalVT added in v0.10.0 

func (m *DirectiveInfo) MarshalVT() (dAtA []byte, err error)

func (*DirectiveInfo) ProtoMessage 

func (*DirectiveInfo) ProtoMessage()

func (*DirectiveInfo) ProtoReflect added in v0.10.1 

func (x *DirectiveInfo) ProtoReflect() protoreflect.Message

func (*DirectiveInfo) Reset 

func (x *DirectiveInfo) Reset()

func (*DirectiveInfo) SizeVT added in v0.10.0 

func (m *DirectiveInfo) SizeVT() (n int)

func (*DirectiveInfo) String 

func (x *DirectiveInfo) String() string

func (*DirectiveInfo) UnmarshalVT added in v0.10.0 

func (m *DirectiveInfo) UnmarshalVT(dAtA []byte) error

type DirectiveState 

type DirectiveState struct {

	// Info is the directive info.
	Info *DirectiveInfo `protobuf:"bytes,1,opt,name=info,proto3" json:"info,omitempty"` // TODO result info
	// contains filtered or unexported fields
}

DirectiveState contains directive info and state info in protobuf form.

func NewDirectiveState 

func NewDirectiveState(di Instance) *DirectiveState

NewDirectiveState constructs a new DirectiveState from a running directive.

func (*DirectiveState) CloneGenericVT added in v0.12.3 

func (m *DirectiveState) CloneGenericVT() proto.Message

func (*DirectiveState) CloneVT added in v0.12.3 

func (m *DirectiveState) CloneVT() *DirectiveState

func (*DirectiveState) Descriptor deprecated 

func (*DirectiveState) Descriptor() ([]byte, []int)

Deprecated: Use DirectiveState.ProtoReflect.Descriptor instead.

func (*DirectiveState) EqualVT added in v0.10.0 

func (this *DirectiveState) EqualVT(that *DirectiveState) bool

func (*DirectiveState) GetInfo 

func (x *DirectiveState) GetInfo() *DirectiveInfo

func (*DirectiveState) MarshalToSizedBufferVT added in v0.10.0 

func (m *DirectiveState) MarshalToSizedBufferVT(dAtA []byte) (int, error)

func (*DirectiveState) MarshalToVT added in v0.10.0 

func (m *DirectiveState) MarshalToVT(dAtA []byte) (int, error)

func (*DirectiveState) MarshalVT added in v0.10.0 

func (m *DirectiveState) MarshalVT() (dAtA []byte, err error)

func (*DirectiveState) ProtoMessage 

func (*DirectiveState) ProtoMessage()

func (*DirectiveState) ProtoReflect added in v0.10.1 

func (x *DirectiveState) ProtoReflect() protoreflect.Message

func (*DirectiveState) Reset 

func (x *DirectiveState) Reset()

func (*DirectiveState) SizeVT added in v0.10.0 

func (m *DirectiveState) SizeVT() (n int)

func (*DirectiveState) String 

func (x *DirectiveState) String() string

func (*DirectiveState) UnmarshalVT added in v0.10.0 

func (m *DirectiveState) UnmarshalVT(dAtA []byte) error

type DirectiveWithEquiv added in v0.19.0 

type DirectiveWithEquiv interface {
	Directive

	// IsEquivalent checks if the other directive is equivalent. If two
	// directives are equivalent, and the new directive does not superceed the
	// old, then the new directive will be merged (de-duplicated) into the old.
	IsEquivalent(other Directive) bool
}

DirectiveWithEquiv contains a check to see if it is equivalent to another directive.

type DirectiveWithSuperceeds added in v0.19.0 

type DirectiveWithSuperceeds interface {
	DirectiveWithEquiv

	// Superceeds checks if the directive overrides another.
	// The other directive will be canceled if superceded.
	Superceeds(other Directive) bool
}

DirectiveWithSuperceeds contains a check to see if the directive superceeds another.

type Handler 

type Handler interface {
	// HandleDirective asks if the handler can resolve the directive.
	// If it can, it returns resolver(s). If not, returns nil.
	// It is safe to add a reference to the directive during this call.
	// The context passed is canceled when the directive instance expires.
	HandleDirective(context.Context, Instance) ([]Resolver, error)
}

Handler handles new reference instances.

type IdleCallback added in v0.8.7 

type IdleCallback func(errs []error)

IdleCallback is called when the directive becomes idle. Errs is the list of non-nil resolver errors.

type Instance 

type Instance interface {
	// GetContext returns a context that is canceled when Instance is released.
	GetContext() context.Context

	// GetDirective returns the underlying directive object.
	GetDirective() Directive

	// GetDirectiveIdent returns a human-readable string identifying the directive.
	//
	// Ex: DoSomething or DoSomething<param=foo>
	GetDirectiveIdent() string

	// GetResolverErrors returns a snapshot of any errors returned by resolvers.
	GetResolverErrors() []error

	// AddReference adds a reference to the directive.
	// cb is called for each value.
	// cb calls should return immediately.
	// the release callback is called immediately if already released
	// If marked as a weak ref, the handler will not count towards the ref count.
	// will never return nil
	AddReference(cb ReferenceHandler, weakRef bool) Reference

	// AddDisposeCallback adds a callback that will be called when the instance
	// is disposed, either when Close() is called, or when the reference count
	// drops to zero. The callback may occur immediately if the instance is
	// already disposed, but will be made in a new goroutine.
	// Returns a callback release function.
	AddDisposeCallback(cb func()) func()

	// AddIdleCallback adds a callback that will be called when idle.
	// The callback is called exactly once.
	// Returns a callback release function.
	AddIdleCallback(cb IdleCallback) func()

	// CloseIfUnreferenced cancels the directive instance if there are no refs.
	//
	// This bypasses the unref dispose timer.
	// If inclWeakRefs=true, keeps the instance if there are any weak refs.
	// Returns if the directive instance was closed.
	CloseIfUnreferenced(inclWeakRefs bool) bool

	// Close cancels the directive instance and removes the directive.
	Close()
}

Instance tracks a directive with reference counts and resolution state.

type Networked 

type Networked interface {
	// Directive indicates this is a directive.
	Directive
	// GetNetworkedCodec returns the encoder / decoder for this directive.
	// The same encoder/decoder should also be compatible with the results.
	GetNetworkedCodec() NetworkedCodec
}

Networked is a directive which can be serialized and uniquely identified across IPC domains.

type NetworkedCodec 

type NetworkedCodec interface {
	// Marshal encodes the networked directive.
	Marshal(Networked) ([]byte, error)
	// Unmarshal decodes the data to the networked directive.
	// The type must match the expected type for the codec.
	Unmarshal([]byte, Networked) error
}

NetworkedCodec is the encoder/decoder for a networked directive.

type ProtoDebugValue 

type ProtoDebugValue struct {

	// Key is the debug value key.
	Key string `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
	// Values are the debug value values.
	Values []string `protobuf:"bytes,2,rep,name=values,proto3" json:"values,omitempty"`
	// contains filtered or unexported fields
}

ProtoDebugValue is a debug value.

func NewProtoDebugValues 

func NewProtoDebugValues(dv DebugValues) []*ProtoDebugValue

NewProtoDebugValues constructs a new ProtoDebugValue set.

func (*ProtoDebugValue) CloneGenericVT added in v0.12.3 

func (m *ProtoDebugValue) CloneGenericVT() proto.Message

func (*ProtoDebugValue) CloneVT added in v0.12.3 

func (m *ProtoDebugValue) CloneVT() *ProtoDebugValue

func (*ProtoDebugValue) Descriptor deprecated 

func (*ProtoDebugValue) Descriptor() ([]byte, []int)

Deprecated: Use ProtoDebugValue.ProtoReflect.Descriptor instead.

func (*ProtoDebugValue) EqualVT added in v0.10.0 

func (this *ProtoDebugValue) EqualVT(that *ProtoDebugValue) bool

func (*ProtoDebugValue) GetKey 

func (x *ProtoDebugValue) GetKey() string

func (*ProtoDebugValue) GetValues 

func (x *ProtoDebugValue) GetValues() []string

func (*ProtoDebugValue) MarshalToSizedBufferVT added in v0.10.0 

func (m *ProtoDebugValue) MarshalToSizedBufferVT(dAtA []byte) (int, error)

func (*ProtoDebugValue) MarshalToVT added in v0.10.0 

func (m *ProtoDebugValue) MarshalToVT(dAtA []byte) (int, error)

func (*ProtoDebugValue) MarshalVT added in v0.10.0 

func (m *ProtoDebugValue) MarshalVT() (dAtA []byte, err error)

func (*ProtoDebugValue) ProtoMessage 

func (*ProtoDebugValue) ProtoMessage()

func (*ProtoDebugValue) ProtoReflect added in v0.10.1 

func (x *ProtoDebugValue) ProtoReflect() protoreflect.Message

func (*ProtoDebugValue) Reset 

func (x *ProtoDebugValue) Reset()

func (*ProtoDebugValue) SizeVT added in v0.10.0 

func (m *ProtoDebugValue) SizeVT() (n int)

func (*ProtoDebugValue) String 

func (x *ProtoDebugValue) String() string

func (*ProtoDebugValue) UnmarshalVT added in v0.10.0 

func (m *ProtoDebugValue) UnmarshalVT(dAtA []byte) error

type Reference 

type Reference interface {
	// Release releases the reference.
	Release()
}

Reference is a reference to a directive. This is used to expire directive handles.

type ReferenceHandler 

type ReferenceHandler interface {
	// HandleValueAdded is called when a value is added to the directive.
	// Should not block.
	// Avoid calling directive functions in this routine.
	HandleValueAdded(Instance, AttachedValue)
	// HandleValueRemoved is called when a value is removed from the directive.
	// Should not block.
	// Avoid calling directive functions in this routine.
	HandleValueRemoved(Instance, AttachedValue)
	// HandleInstanceDisposed is called when a directive instance is disposed.
	// This will occur if Close() is called on the directive instance.
	// Avoid calling directive functions in this routine.
	HandleInstanceDisposed(Instance)
}

ReferenceHandler handles values emitted by the directive instance.

type Resolver 

type Resolver interface {
	// Resolve resolves the values, emitting them to the handler.
	// The resolver may be canceled and restarted multiple times.
	// Any fatal error resolving the value is returned.
	// The resolver will not be retried after returning an error.
	// Values will be maintained from the previous call.
	Resolve(ctx context.Context, handler ResolverHandler) error
}

Resolver resolves values for directives.

func NewResolver added in v0.18.0 

func NewResolver(res Resolver, err error) ([]Resolver, error)

NewResolver checks the error and returns a resolver slice if err == nil.

func R added in v0.18.0 

func R(res Resolver, err error) ([]Resolver, error)

R is a shortcut for NewResolver.

func Resolvers added in v0.17.0 

func Resolvers(resolvers ...Resolver) []Resolver

Resolvers constructs a resolver slice, ignoring nil entries.

type ResolverHandler 

type ResolverHandler interface {
	// AddValue adds a value to the result, returning success and an ID. If
	// AddValue returns false, value was rejected. A rejected value should be
	// released immediately. If the value limit is reached, the value may not be
	// accepted. The value may be accepted, immediately before the resolver is
	// canceled (limit reached). It is always safe to call RemoveValue with the
	// ID at any time, even if the resolver is cancelled.
	AddValue(Value) (id uint32, accepted bool)
	// RemoveValue removes a value from the result, returning found.
	// It is safe to call this function even if the resolver is canceled.
	RemoveValue(id uint32) (val Value, found bool)
	// MarkIdle marks the resolver as idle.
	// If the resolver returns nil or an error, it's also marked as idle.
	MarkIdle()
	// CountValues returns the number of values that were set.
	// if allResolvers=false, returns the number set by this ResolverHandler.
	// if allResolvers=true, returns the number set by all resolvers.
	CountValues(allResolvers bool) int
	// ClearValues removes any values that were set by this ResolverHandler.
	// Returns list of value IDs that were removed.
	ClearValues() []uint32
}

ResolverHandler handles values emitted by the resolver.

type RetryResolver added in v0.18.2 

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

RetryResolver wraps a Resolver with retry logic.

func NewRetryResolver added in v0.18.2 

func NewRetryResolver(le *logrus.Entry, res Resolver, bo backoff.BackOff) *RetryResolver

NewRetryResolver constructs a new retry resolver.

func (*RetryResolver) Resolve added in v0.18.2 

func (r *RetryResolver) Resolve(ctx context.Context, handler ResolverHandler) error

Resolve resolves the values, emitting them to the handler.

type Value 

type Value interface{}

Value satisfies a directive.

type ValueOptions 

type ValueOptions struct {
	// MaxValueCount indicates a maximum number of values to retrieve.
	// The resolvers will be canceled when this many values are gathered.
	// If zero, accepts infinite values.
	MaxValueCount int

	// MaxValueHardCap indicates MaxValueCount is a hard cap. If it is not a
	// hard cap, any values found after resolvers are canceled is accepted. If
	// it is a hard cap, any values found after resolvers are canceled will be
	// rejected.
	MaxValueHardCap bool

	// UnrefDisposeDur is the duration to wait to dispose a directive after all
	// references have been released.
	UnrefDisposeDur time.Duration

	// UnrefDisposeEmptyImmediate indicates we should immediately dispose a
	// directive that has become unreferenced if there are no associated Values
	// with the directive (it is unresolved) regardless of UnrefDisposeDur.
	UnrefDisposeEmptyImmediate bool
}

ValueOptions are options related to value handling.

type ValueResolver added in v0.15.5 

type ValueResolver[T any] struct {
	// contains filtered or unexported fields
}

ValueResolver resolves a directive with a static list of values.

func NewValueResolver added in v0.15.5 

func NewValueResolver[T any](vals []T) *ValueResolver[T]

NewValueResolver constructs a new ValueResolver.

func (*ValueResolver[T]) Resolve added in v0.15.5 

func (r *ValueResolver[T]) Resolve(ctx context.Context, handler ResolverHandler) error

Resolve resolves the values, emitting them to the handler.

Source Files

View all Source files

Directories

Path Synopsis

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.