directive

package
v0.28.5 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 2023 License: MIT Imports: 14 Imported by: 43

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) CloneMessageVT added in v0.23.6 

func (m *DirectiveInfo) CloneMessageVT() 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) EqualMessageVT added in v0.23.6 

func (this *DirectiveInfo) EqualMessageVT(thatMsg proto.Message) bool

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) CloneMessageVT added in v0.23.6 

func (m *DirectiveState) CloneMessageVT() 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) EqualMessageVT added in v0.23.6 

func (this *DirectiveState) EqualMessageVT(thatMsg proto.Message) bool

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 GetterResolver added in v0.23.8 

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

GetterResolver resolves a directive with a getter function.

func NewGetterResolver added in v0.23.8 

func NewGetterResolver[T any](getter func(ctx context.Context) (T, error)) *GetterResolver[T]

NewGetterResolver constructs a new GetterResolver.

func (*GetterResolver[T]) Resolve added in v0.23.8 

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

Resolve resolves the values, emitting them to the handler.

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 the directive becomes idle.
	// May be called multiple times if the directive is restarted.
	// 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) CloneMessageVT added in v0.23.6 

func (m *ProtoDebugValue) CloneMessageVT() 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) EqualMessageVT added in v0.23.6 

func (this *ProtoDebugValue) EqualMessageVT(thatMsg proto.Message) bool

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 RefCountResolver added in v0.22.1 

type RefCountResolver[T comparable] struct {
	// contains filtered or unexported fields
}

RefCountResolver resolves a directive with a RefCount container.

Adds a reference, waits for a value, and adds it to the handler. Removes the value and waits for a new one when the value is released. Calls MarkIdle when the value has been added. buildValue can be nil if useCtx is set, uses the refcount resolver context to start the refcount container. If buildValue is set, will be called with the values. if buildValue returns nil, nil, ignores the value.

func NewRefCountResolver added in v0.22.1 

func NewRefCountResolver[T comparable](
	rc *refcount.RefCount[T],
	useCtx bool,
	buildValue func(val T) (Value, error),
) *RefCountResolver[T]

NewRefCountResolver constructs a new RefCountResolver.

if useCtx is set, uses the refcount resolver context to start the refcount container.

func (*RefCountResolver[T]) Resolve added in v0.22.1 

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

Resolve resolves the values, emitting them to the handler.

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.