directive

package
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Jun 3, 2022 License: Apache-2.0 Imports: 9 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")
)

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 {
	// 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.
	// cb will receive the initial value set as part of the AddDirective
	//   call, so be careful to 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).
	// If the handler returns an error for the initial set, will be returned.
	AddHandler(handler Handler) error

	// RemoveHandler removes a directive handler.
	RemoveHandler(Handler)

	// GetDirectives returns a list of all currently executing directives.
	GetDirectives() []Instance
}

Controller manages directives.

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

	// 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

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

	// GetName returns the directive's type name.
	// This is not necessarily unique, and is primarily intended 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"`
	XXX_NoUnkeyedLiteral struct{}           `json:"-"`
	XXX_unrecognized     []byte             `json:"-"`
	XXX_sizecache        int32              `json:"-"`
}

DirectiveInfo contains directive information in protobuf form.

func NewDirectiveInfo 

func NewDirectiveInfo(dir Directive) *DirectiveInfo

NewDirectiveInfo constructs a new DirectiveInfo from a directive.

func (*DirectiveInfo) Descriptor 

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

func (*DirectiveInfo) EqualVT added in v0.10.0 

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

func (*DirectiveInfo) GetDebugVals 

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

func (*DirectiveInfo) GetName 

func (m *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) Reset 

func (m *DirectiveInfo) Reset()

func (*DirectiveInfo) SizeVT added in v0.10.0 

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

func (*DirectiveInfo) String 

func (m *DirectiveInfo) String() string

func (*DirectiveInfo) UnmarshalVT added in v0.10.0 

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

func (*DirectiveInfo) XXX_DiscardUnknown 

func (m *DirectiveInfo) XXX_DiscardUnknown()

func (*DirectiveInfo) XXX_Marshal 

func (m *DirectiveInfo) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*DirectiveInfo) XXX_Merge 

func (m *DirectiveInfo) XXX_Merge(src proto.Message)

func (*DirectiveInfo) XXX_Size 

func (m *DirectiveInfo) XXX_Size() int

func (*DirectiveInfo) XXX_Unmarshal 

func (m *DirectiveInfo) XXX_Unmarshal(b []byte) error

type DirectiveState 

type DirectiveState struct {
	// Info is the directive info.
	Info                 *DirectiveInfo `protobuf:"bytes,1,opt,name=info,proto3" json:"info,omitempty"`
	XXX_NoUnkeyedLiteral struct{}       `json:"-"`
	XXX_unrecognized     []byte         `json:"-"`
	XXX_sizecache        int32          `json:"-"`
}

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) Descriptor 

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

func (*DirectiveState) EqualVT added in v0.10.0 

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

func (*DirectiveState) GetInfo 

func (m *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) Reset 

func (m *DirectiveState) Reset()

func (*DirectiveState) SizeVT added in v0.10.0 

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

func (*DirectiveState) String 

func (m *DirectiveState) String() string

func (*DirectiveState) UnmarshalVT added in v0.10.0 

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

func (*DirectiveState) XXX_DiscardUnknown 

func (m *DirectiveState) XXX_DiscardUnknown()

func (*DirectiveState) XXX_Marshal 

func (m *DirectiveState) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*DirectiveState) XXX_Merge 

func (m *DirectiveState) XXX_Merge(src proto.Message)

func (*DirectiveState) XXX_Size 

func (m *DirectiveState) XXX_Size() int

func (*DirectiveState) XXX_Unmarshal 

func (m *DirectiveState) XXX_Unmarshal(b []byte) error

type Handler 

type Handler interface {
	// HandleDirective asks if the handler can resolve the directive.
	// If it can, it returns a resolver. If not, returns nil.
	// Any exceptional errors are returned for logging.
	// 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 {
	// GetDirective returns the underlying directive object.
	GetDirective() Directive

	// 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.
	// Will return nil if the directive is already expired.
	// If marked as a weak ref, the handler will not count towards the ref count.
	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()

	// Close cancels the directive instance.
	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"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

ProtoDebugValue is a debug value.

func NewProtoDebugValues 

func NewProtoDebugValues(dv DebugValues) []*ProtoDebugValue

NewProtoDebugValues constructs a new ProtoDebugValue set.

func (*ProtoDebugValue) Descriptor 

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

func (*ProtoDebugValue) EqualVT added in v0.10.0 

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

func (*ProtoDebugValue) GetKey 

func (m *ProtoDebugValue) GetKey() string

func (*ProtoDebugValue) GetValues 

func (m *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) Reset 

func (m *ProtoDebugValue) Reset()

func (*ProtoDebugValue) SizeVT added in v0.10.0 

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

func (*ProtoDebugValue) String 

func (m *ProtoDebugValue) String() string

func (*ProtoDebugValue) UnmarshalVT added in v0.10.0 

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

func (*ProtoDebugValue) XXX_DiscardUnknown 

func (m *ProtoDebugValue) XXX_DiscardUnknown()

func (*ProtoDebugValue) XXX_Marshal 

func (m *ProtoDebugValue) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*ProtoDebugValue) XXX_Merge 

func (m *ProtoDebugValue) XXX_Merge(src proto.Message)

func (*ProtoDebugValue) XXX_Size 

func (m *ProtoDebugValue) XXX_Size() int

func (*ProtoDebugValue) XXX_Unmarshal 

func (m *ProtoDebugValue) XXX_Unmarshal(b []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.

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)
}

ResolverHandler handles values emitted by the resolver.

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
}

ValueOptions are options related to value handling.

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.