directive

package
v0.47.7 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2024 License: MIT Imports: 19 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 ErrDirectiveDisposed = errors.New("directive disposed unexpectedly")

ErrDirectiveDisposed is returned when the directive was unexpectedly disposed.

Functions

This section is empty.

Types

type AccessResolver added in v0.47.5 

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

AccessResolver resolves a directive with an access function.

func NewAccessResolver added in v0.47.5 

func NewAccessResolver[T comparable](getter AccessResolverFunc[T]) *AccessResolver[T]

NewAccessResolver constructs a new AccessResolver.

func (*AccessResolver[T]) Resolve added in v0.47.5 

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

Resolve resolves the values, emitting them to the handler.

type AccessResolverFunc added in v0.47.5 

type AccessResolverFunc[T comparable] func(ctx context.Context, released func()) (T, func(), error)

AccessResolverFunc resolves a value similarly to a RefCount container.

Accepts a released callback which can be called when the returned value is invalid. Returns a release function which will be called when the returned value is no longer needed.

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.

func NewAttachedValue added in v0.34.0 

func NewAttachedValue(vid uint32, val Value) AttachedValue

NewAttachedValue constructs a new typed attached value.

type CallbackHandler added in v0.29.2 

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

CallbackHandler is a reference handler that uses function callbacks.

func (*CallbackHandler) HandleInstanceDisposed added in v0.29.2 

func (h *CallbackHandler) HandleInstanceDisposed(Instance)

HandleInstanceDisposed is called when a directive instance is disposed. This will occur if Close() is called on the directive instance.

func (*CallbackHandler) HandleValueAdded added in v0.29.2 

func (h *CallbackHandler) HandleValueAdded(
	_ Instance,
	v AttachedValue,
)

HandleValueAdded is called when a value is added to the directive.

func (*CallbackHandler) HandleValueRemoved added in v0.29.2 

func (h *CallbackHandler) HandleValueRemoved(
	_ Instance,
	v AttachedValue,
)

HandleValueRemoved is called when a value is removed from the directive.

type ComparableValue added in v0.33.2 

type ComparableValue interface {
	Value
	comparable
}

ComparableValue is a type constraint for a comparable Value.

type Controller 

type Controller interface {
	// DirectiveLister has GetDirectives.
	DirectiveLister

	// DirectiveAdder has AddDirective.
	DirectiveAdder

	// HandlerAdder has AddHandler.
	HandlerAdder
}

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 DirectiveAdder added in v0.29.2 

type DirectiveAdder 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.
	//
	// Returns the instance, new reference, and any error.
	AddDirective(Directive, ReferenceHandler) (Instance, Reference, error)
}

DirectiveAdder can add a directive to a bus.

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:"debugVals,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() protobuf_go_lite.CloneMessage

func (*DirectiveInfo) CloneVT added in v0.12.3 

func (m *DirectiveInfo) CloneVT() *DirectiveInfo

func (*DirectiveInfo) EqualMessageVT added in v0.23.6 

func (this *DirectiveInfo) EqualMessageVT(thatMsg any) 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) MarshalJSON added in v0.41.0 

func (x *DirectiveInfo) MarshalJSON() ([]byte, error)

MarshalJSON marshals the DirectiveInfo to JSON.

func (*DirectiveInfo) MarshalProtoJSON added in v0.41.0 

func (x *DirectiveInfo) MarshalProtoJSON(s *json.MarshalState)

MarshalProtoJSON marshals the DirectiveInfo message to JSON.

func (*DirectiveInfo) MarshalProtoText added in v0.42.0 

func (x *DirectiveInfo) MarshalProtoText() 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 (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) UnmarshalJSON added in v0.41.0 

func (x *DirectiveInfo) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals the DirectiveInfo from JSON.

func (*DirectiveInfo) UnmarshalProtoJSON added in v0.41.0 

func (x *DirectiveInfo) UnmarshalProtoJSON(s *json.UnmarshalState)

UnmarshalProtoJSON unmarshals the DirectiveInfo message from JSON.

func (*DirectiveInfo) UnmarshalVT added in v0.10.0 

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

type DirectiveLister added in v0.29.2 

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

DirectiveLister can list directives.

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() protobuf_go_lite.CloneMessage

func (*DirectiveState) CloneVT added in v0.12.3 

func (m *DirectiveState) CloneVT() *DirectiveState

func (*DirectiveState) EqualMessageVT added in v0.23.6 

func (this *DirectiveState) EqualMessageVT(thatMsg any) 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) MarshalJSON added in v0.41.0 

func (x *DirectiveState) MarshalJSON() ([]byte, error)

MarshalJSON marshals the DirectiveState to JSON.

func (*DirectiveState) MarshalProtoJSON added in v0.41.0 

func (x *DirectiveState) MarshalProtoJSON(s *json.MarshalState)

MarshalProtoJSON marshals the DirectiveState message to JSON.

func (*DirectiveState) MarshalProtoText added in v0.42.0 

func (x *DirectiveState) MarshalProtoText() string

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 (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) UnmarshalJSON added in v0.41.0 

func (x *DirectiveState) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals the DirectiveState from JSON.

func (*DirectiveState) UnmarshalProtoJSON added in v0.41.0 

func (x *DirectiveState) UnmarshalProtoJSON(s *json.UnmarshalState)

UnmarshalProtoJSON unmarshals the DirectiveState message from JSON.

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 FuncResolver added in v0.33.0 

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

FuncResolver resolves a directive with a function.

func NewFuncResolver added in v0.33.0 

func NewFuncResolver(fn func(ctx context.Context, handler ResolverHandler) error) *FuncResolver

NewFuncResolver constructs a new FuncResolver.

func (*FuncResolver) Resolve added in v0.33.0 

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

Resolve resolves the values, emitting them to the handler.

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 passed context is canceled when the directive instance expires.
	// NOTE: the passed context is not canceled when the handler is removed.
	HandleDirective(context.Context, Instance) ([]Resolver, error)
}

Handler handles directives.

type HandlerAdder added in v0.29.2 

type HandlerAdder interface {
	// 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)
}

HandlerAdder can add a handler to a bus.

type HandlerFunc added in v0.46.0 

type HandlerFunc = func(context.Context, Instance) ([]Resolver, error)

HandlerFunc 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 passed context is canceled when the directive instance expires. NOTE: the passed context is not canceled when the handler is removed.

type IdleCallback added in v0.8.7 

type IdleCallback func(isIdle bool, errs []error)

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

func NewErrChIdleCallback added in v0.39.1 

func NewErrChIdleCallback(errCh chan<- error, waitIdle bool) IdleCallback

NewErrChIdleCallback builds an IdleCallback which writes an error to a channel if any of the resolvers returned any error other than context.Canceled.

If waitIdle is set, waits for the directive to be idle before checking errs. Skips writing to the channel if it is full, use a buffered channel of size 1.

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 idle state changes.
	// Called immediately with the initial state.
	// 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 KeyedGetterFunc added in v0.30.3 

type KeyedGetterFunc[K, V comparable] func(ctx context.Context, key K, release func()) (V, func(), error)

KeyedGetterFunc is a keyed getter function to resolve a keyed resolver.

release is a function to call if the value is released. return nil, nil, nil for not found. return a release function if necessary

type KeyedGetterResolver added in v0.30.3 

type KeyedGetterResolver[K, V comparable] struct {
	// contains filtered or unexported fields
}

KeyedGetterResolver resolves a directive with a keyed getter function.

func NewKeyedGetterResolver added in v0.30.3 

func NewKeyedGetterResolver[K, V comparable](getter KeyedGetterFunc[K, V], key K) *KeyedGetterResolver[K, V]

NewKeyedGetterResolver constructs a new KeyedGetterResolver.

func (*KeyedGetterResolver[K, V]) Resolve added in v0.30.3 

func (r *KeyedGetterResolver[K, V]) Resolve(ctx context.Context, handler ResolverHandler) error

Resolve resolves the values, emitting them to the handler.

type KeyedRefCountResolver added in v0.29.0 

type KeyedRefCountResolver[K, V comparable] struct {
	// contains filtered or unexported fields
}

KeyedRefCountResolver resolves a directive with a Keyed 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 buildValue is set, will be called with the values. if buildValue returns nil, nil, ignores the value.

func NewKeyedRefCountResolver added in v0.29.0 

func NewKeyedRefCountResolver[K, V comparable](
	rc *keyed.KeyedRefCount[K, V],
	key K,
	buildValue func(ctx context.Context, val V) (Value, error),
) *KeyedRefCountResolver[K, V]

NewKeyedRefCountResolver constructs a new KeyedRefCountResolver.

func (*KeyedRefCountResolver[K, V]) Resolve added in v0.29.0 

func (r *KeyedRefCountResolver[K, V]) Resolve(ctx context.Context, handler ResolverHandler) error

Resolve resolves the values, emitting them to the handler.

type LogHandler added in v0.47.0 

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

LogHandler is a reference handler that logs when values are added and removed.

Optionally wraps a base ReferenceHandler,

func (*LogHandler) HandleInstanceDisposed added in v0.47.0 

func (h *LogHandler) HandleInstanceDisposed(di Instance)

HandleInstanceDisposed is called when a directive instance is disposed. This will occur if Close() is called on the directive instance.

func (*LogHandler) HandleValueAdded added in v0.47.0 

func (h *LogHandler) HandleValueAdded(
	di Instance,
	v AttachedValue,
)

HandleValueAdded is called when a value is added to the directive.

func (*LogHandler) HandleValueRemoved added in v0.47.0 

func (h *LogHandler) HandleValueRemoved(
	di Instance,
	v AttachedValue,
)

HandleValueRemoved is called when a value is removed from the directive.

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() protobuf_go_lite.CloneMessage

func (*ProtoDebugValue) CloneVT added in v0.12.3 

func (m *ProtoDebugValue) CloneVT() *ProtoDebugValue

func (*ProtoDebugValue) EqualMessageVT added in v0.23.6 

func (this *ProtoDebugValue) EqualMessageVT(thatMsg any) 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) MarshalJSON added in v0.41.0 

func (x *ProtoDebugValue) MarshalJSON() ([]byte, error)

MarshalJSON marshals the ProtoDebugValue to JSON.

func (*ProtoDebugValue) MarshalProtoJSON added in v0.41.0 

func (x *ProtoDebugValue) MarshalProtoJSON(s *json.MarshalState)

MarshalProtoJSON marshals the ProtoDebugValue message to JSON.

func (*ProtoDebugValue) MarshalProtoText added in v0.42.0 

func (x *ProtoDebugValue) MarshalProtoText() 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 (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) UnmarshalJSON added in v0.41.0 

func (x *ProtoDebugValue) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals the ProtoDebugValue from JSON.

func (*ProtoDebugValue) UnmarshalProtoJSON added in v0.41.0 

func (x *ProtoDebugValue) UnmarshalProtoJSON(s *json.UnmarshalState)

UnmarshalProtoJSON unmarshals the ProtoDebugValue message from JSON.

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, R ComparableValue] 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 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]) *RefCountResolver[T, T]

NewRefCountResolver constructs a new RefCountResolver.

This is the simplified constructor, use NewRefCountResolverWithXfrm to transform the value.

func NewRefCountResolverWithXfrm added in v0.38.0 

func NewRefCountResolverWithXfrm[T comparable, R ComparableValue](
	rc *refcount.RefCount[T],
	buildValue func(ctx context.Context, val T) (R, error),
) *RefCountResolver[T, R]

NewRefCountResolverWithXfrm constructs a new RefCountResolver with a transform func.

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

func (r *RefCountResolver[T, R]) 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.

func NewCallbackHandler added in v0.29.2 

func NewCallbackHandler(
	valCb func(AttachedValue),
	removedCb func(AttachedValue),
	disposeCb func(),
) ReferenceHandler

NewCallbackHandler wraps callback functions into a handler object.

func NewLogHandler added in v0.47.0 

func NewLogHandler(
	le *logrus.Entry,
	base ReferenceHandler,
) ReferenceHandler

NewLogHandler constructs a logger ReferenceHandler.

If set, base will be called after logging the values. base can be nil le can be nil

func NewTypedCallbackHandler added in v0.47.0 

func NewTypedCallbackHandler[T ComparableValue](
	valCb func(TypedAttachedValue[T]),
	removedCb func(TypedAttachedValue[T]),
	disposeCb func(),
	unknownTypeHandler ReferenceHandler,
) ReferenceHandler

NewTypedCallbackHandler wraps callback functions into a handler object.

unknownTypeHandler can be nil

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 {
	ValueHandler

	// MarkIdle marks the resolver as idle or not-idle.
	// If the resolver returns nil or an error, it's also marked as idle.
	MarkIdle(idle bool)

	// AddValueRemovedCallback adds a callback that will be called when the
	// given value id is disposed or removed.
	//
	// The callback will be called if the value is removed for any reason,
	// including if the parent resolver, handler, or directive are removed.
	//
	// The callback might be called immediately if the value was already removed.
	//
	// Returns a release function to clear the callback early.
	AddValueRemovedCallback(id uint32, cb func()) func()

	// AddResolverRemovedCallback adds a callback that will be called when the
	// directive resolver is removed.
	//
	// The callback will be called if the resolver is removed for any reason,
	// including if the parent resolver, handler, or directive are removed.
	//
	// The callback might be called immediately if the resolver was already removed.
	//
	// Returns a release function to clear the callback early.
	AddResolverRemovedCallback(cb func()) func()

	// AddResolver adds a resolver as a child of the current resolver.
	//
	// The child resolver will be removed if the parent handler is removed.
	//
	// The callback will be called if the child resolver is removed for any
	// reason, including if the parent resolver, handler, or directive are
	// removed.
	//
	// The callback might be called immediately if the child resolver was
	// already removed or not created.
	//
	// Returns a release function to clear and stop the resolver early.
	// Does nothing if res == nil returning an empty release func.
	AddResolver(res Resolver, cb func()) func()
}

ResolverHandler handles values emitted by the resolver and provides utils for 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 TransformAttachedValueFunc added in v0.29.2 

type TransformAttachedValueFunc[T Value] func(ctx context.Context, val AttachedValue) (rval T, rel func(), ok bool, err error)

TransformAttachedValueFunc transforms an AttachedValue. rval is the returned transformed value to emit to the handler (if any). rel is the release function to call when the value is no longer valid (if any). rval is ignored if ok = false. err, if any, will unwind the resolver with the error.

type TransformResolver added in v0.29.2 

type TransformResolver[T Value] struct {
	// contains filtered or unexported fields
}

TransformResolver resolves a directive by adding another directive and transforming the results. T is the type of the value that we will yield to the handler. xfrm returns the transformed value to emit to the handler, bool true/false to emit the value, and any error. if xfrm returns an error the entire resolver unwinds with the error. NOTE: xfrm must not block as it will block the CallbackHandler.

func NewTransformResolver added in v0.29.2 

func NewTransformResolver[T Value](adder DirectiveAdder, dir Directive, xfrm TransformAttachedValueFunc[T]) *TransformResolver[T]

NewTransformResolver constructs a new TransformResolver.

func (*TransformResolver[T]) Resolve added in v0.29.2 

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

Resolve resolves the values, emitting them to the handler.

type TransformTypedAttachedValueFunc added in v0.47.0 

type TransformTypedAttachedValueFunc[V ComparableValue, T Value] func(ctx context.Context, val TypedAttachedValue[V]) (rval T, rel func(), ok bool, err error)

TransformTypedAttachedValueFunc transforms a TypedAttachedValue. rval is the returned transformed value to emit to the handler (if any). rel is the release function to call when the value is no longer valid (if any). rval is ignored if ok = false. err, if any, will unwind the resolver with the error.

type TransformValueFunc added in v0.46.1 

type TransformValueFunc[T, R Value] func(ctx context.Context, val T) (rval R, ok bool, err error)

TransformValueFunc transforms a value. rval is the returned transformed value to emit to the handler (if any). rval is ignored if ok = false. err, if any, will unwind the resolver with the error.

type TransformedAttachedValue added in v0.36.3 

type TransformedAttachedValue[T, E ComparableValue] interface {
	TypedAttachedValue[T]

	// GetTransformedValue returns the transformed value.
	GetTransformedValue() E
}

TransformedAttachedValue is an AttachedValue with a transformed value.

func NewTransformedAttachedValue added in v0.36.3 

func NewTransformedAttachedValue[T, E ComparableValue](
	tav TypedAttachedValue[T],
	xfrm E,
) TransformedAttachedValue[T, E]

NewTransformedAttachedValue builds a new TransformedAttachedValue.

type TypedAttachedValue added in v0.34.0 

type TypedAttachedValue[T ComparableValue] interface {
	// GetValueID returns the value ID.
	GetValueID() uint32
	// GetValue returns the value.
	GetValue() T
}

TypedAttachedValue is a typed value with some metadata.

func NewTypedAttachedValue added in v0.34.0 

func NewTypedAttachedValue[T ComparableValue](vid uint32, val T) TypedAttachedValue[T]

NewTypedAttachedValue constructs a new typed attached value.

type TypedCallbackHandler added in v0.47.0 

type TypedCallbackHandler[T ComparableValue] struct {
	// contains filtered or unexported fields
}

TypedCallbackHandler is a generic reference handler that uses function callbacks.

Values with unknown type are optionally passed to the optional unknownTypeHandler.

func (*TypedCallbackHandler[T]) HandleInstanceDisposed added in v0.47.0 

func (h *TypedCallbackHandler[T]) HandleInstanceDisposed(i Instance)

HandleInstanceDisposed is called when a directive instance is disposed. This will occur if Close() is called on the directive instance.

func (*TypedCallbackHandler[T]) HandleValueAdded added in v0.47.0 

func (h *TypedCallbackHandler[T]) HandleValueAdded(
	di Instance,
	v AttachedValue,
)

HandleValueAdded is called when a value is added to the directive.

func (*TypedCallbackHandler[T]) HandleValueRemoved added in v0.47.0 

func (h *TypedCallbackHandler[T]) HandleValueRemoved(
	di Instance,
	v AttachedValue,
)

HandleValueRemoved is called when a value is removed from the directive.

type TypedTransformResolver added in v0.47.0 

type TypedTransformResolver[V ComparableValue, T Value] struct {
	// contains filtered or unexported fields
}

TypedTransformResolver resolves a directive by adding another directive and transforming the results. V is the type of the input TypedAttachedValue. T is the type of the value that we will yield to the handler. xfrm returns the transformed value to emit to the handler, bool true/false to emit the value, and any error. if xfrm returns an error the entire resolver unwinds with the error. NOTE: xfrm must not block as it will block the TypedCallbackHandler.

func NewTypedTransformResolver added in v0.47.0 

func NewTypedTransformResolver[V ComparableValue, T Value](
	adder DirectiveAdder,
	dir Directive,
	xfrm TransformTypedAttachedValueFunc[V, T],
	unknownTypeHandler ReferenceHandler,
) *TypedTransformResolver[V, T]

NewTypedTransformResolver constructs a new TypedTransformResolver.

func (*TypedTransformResolver[V, T]) Resolve added in v0.47.0 

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

Resolve resolves the values, emitting them to the handler.

type UniqueListResolver added in v0.35.2 

type UniqueListResolver[K, V comparable] struct {
	*unique.KeyedList[K, V]
}

UniqueListResolver accepts and de-duplicates a list of keyed objects. The objects are emitted to the ValueHandler. If an object changes, the old value is removed & replaced.

cmp checks if two values are equal. if equal, the old version of the value is used.

K is the key type V is the value type

func NewUniqueListResolver added in v0.35.2 

func NewUniqueListResolver[K, V comparable](
	getKey func(v V) K,
	cmp func(k K, a, b V) bool,
	hnd ValueHandler,
) *UniqueListResolver[K, V]

NewUniqueListResolver constructs a new UniqueListResolver.

type UniqueListXfrmResolver added in v0.36.0 

type UniqueListXfrmResolver[K, V comparable, O any] struct {
	*unique.KeyedList[K, V]
}

UniqueListXfrmResolver accepts and de-duplicates a list of keyed objects. The objects are transformed and emitted to the ValueHandler. If an object changes, the old value is removed & replaced.

cmp checks if two values are equal. if equal, the old version of the value is used.

xfrm transforms the values before emitting them. if xfrm returns false the value is dropped.

K is the key type V is the value type O is the type to emit to the resolver

func NewUniqueListXfrmResolver added in v0.36.0 

func NewUniqueListXfrmResolver[K, V comparable, O any](
	getKey func(v V) K,
	cmp func(k K, a, b V) bool,
	xfrm func(k K, v V) (O, bool),
	hnd ValueHandler,
) *UniqueListXfrmResolver[K, V, O]

NewUniqueListXfrmResolver constructs a new UniqueListXfrmResolver.

type UniqueMapResolver added in v0.35.2 

type UniqueMapResolver[K, V comparable] struct {
	*unique.KeyedMap[K, V]
}

UniqueMapResolver accepts and de-duplicates a list of keyed objects. The objects are emitted to the ValueHandler. If an object changes, the old value is removed & replaced.

cmp checks if two values are equal. if equal, the old version of the value is used.

K is the key type V is the value type

func NewUniqueMapResolver added in v0.35.2 

func NewUniqueMapResolver[K, V comparable](
	cmp func(k K, a V, b V) bool,
	hnd ValueHandler,
) *UniqueMapResolver[K, V]

NewUniqueMapResolver constructs a new UniqueMapResolver.

type UniqueMapXfrmResolver added in v0.36.0 

type UniqueMapXfrmResolver[K, V comparable, O any] struct {
	*unique.KeyedMap[K, V]
}

UniqueMapXfrmResolver accepts and de-duplicates a list of keyed objects. The objects are transformed and emitted to the ValueHandler. If an object changes, the old value is removed & replaced.

cmp checks if two values are equal. if equal, the old version of the value is used.

xfrm transforms the values before emitting them. if xfrm returns false the value is dropped.

K is the key type V is the value type O is the type to emit to the resolver

func NewUniqueMapXfrmResolver added in v0.36.0 

func NewUniqueMapXfrmResolver[K, V comparable, O any](
	cmp func(k K, a V, b V) bool,
	xfrm func(k K, v V) (O, bool),
	hnd ValueHandler,
) *UniqueMapXfrmResolver[K, V, O]

NewUniqueMapXfrmResolver constructs a new UniqueMapXfrmResolver.

type Value 

type Value interface{}

Value satisfies a directive.

type ValueHandler added in v0.35.0 

type ValueHandler 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)
	// CountValues returns the number of values that were set.
	// if allResolvers=false, returns the number set by this handler.
	// if allResolvers=true, returns the number set by all resolvers.
	CountValues(allResolvers bool) int
	// ClearValues removes any values that were set by this handler.
	// Returns list of value IDs that were removed.
	ClearValues() []uint32
}

ValueHandler handles values emitted by a resolver.

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.

type WatchableResolver added in v0.46.0 

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

WatchableResolver wraps a Watchable into a resolver.

func NewWatchableResolver added in v0.46.0 

func NewWatchableResolver[T comparable](ctr ccontainer.Watchable[T]) *WatchableResolver[T]

NewWatchableResolver constructs a new retry resolver.

func (*WatchableResolver[T]) Resolve added in v0.46.0 

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

Resolve resolves the values, emitting them to the handler.

type WatchableTransformResolver added in v0.46.1 

type WatchableTransformResolver[T ComparableValue, R Value] struct {
	// contains filtered or unexported fields
}

WatchableTransformResolver wraps a Watchable into a resolver and transforms the values.

func NewWatchableTransformResolver added in v0.46.1 

func NewWatchableTransformResolver[T ComparableValue, R Value](
	ctr ccontainer.Watchable[T],
	xfrm TransformValueFunc[T, R],
) *WatchableTransformResolver[T, R]

NewWatchableTransformResolver constructs a new WatchableTransformResolver.

func (*WatchableTransformResolver[T, R]) Resolve added in v0.46.1 

func (r *WatchableTransformResolver[T, R]) 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.