evaluation

type BoundStoreForTesting ¶

type BoundStoreForTesting = model_tag.BoundStore[object.LocalReference]

BoundStoreForTesting is used to generate mocks that are used by RecursiveComputer's unit tests.

type Computer ¶

type Computer[TReference any, TMetadata model_core.ReferenceMetadata] interface {
	ComputeMessageValue(ctx context.Context, key model_core.Message[proto.Message, TReference], e Environment[TReference, TMetadata]) (model_core.PatchedMessage[proto.Message, TMetadata], error)
	ComputeNativeValue(ctx context.Context, key model_core.Message[proto.Message, TReference], e Environment[TReference, TMetadata]) (any, error)
	IsLookup(typeURL string) bool
	ReturnsNativeValue(typeURL string) bool
}

Computer of values belonging to keys. Keys are always provided in the form of a Protobuf message. The resulting values can either be Protobuf messages, or ones belonging to native Go types.

func NewLeakCheckingComputer[TReference any, TMetadata model_core.ReferenceMetadata](base Computer[TReference, *model_core.LeakCheckingReferenceMetadata[TMetadata]]) Computer[TReference, TMetadata]

type ComputerFactory ¶

type ComputerFactory[TReference any, TMetadata model_core.ReferenceMetadata] interface {
	NewComputer(
		namespace object.Namespace,
		parsedObjectPoolIngester *model_parser.ParsedObjectPoolIngester[TReference],
		objectExporter model_core.ObjectExporter[TReference, object.LocalReference],
	) Computer[TReference, TMetadata]
}

ComputerFactory is called into by the executor to obtain an instance of Computer whenever an evaluation request is received.

type ComputerForTesting ¶

type ComputerForTesting Computer[object.LocalReference, model_core.ReferenceMetadata]

ComputerForTesting is used to generate mocks that are used by RecursiveComputer's unit tests.

type Environment ¶

type Environment[TReference any, TMetadata model_core.ReferenceMetadata] interface {
	model_core.ObjectManager[TReference, TMetadata]

	// Methods that implementations of Computer can invoke to get
	// access to the value of another key.
	GetMessageValue(key model_core.PatchedMessage[proto.Message, TMetadata]) model_core.Message[proto.Message, TReference]
	GetNativeValue(key model_core.PatchedMessage[proto.Message, TMetadata]) (any, bool)
}

Environment that is provided to Computer.Compute*Value() to obtain access to values of other keys, and to attach Merkle tree nodes to computed keys and values.

type KeyState ¶

type KeyState[TReference object.BasicReference, TMetadata model_core.ReferenceMetadata] struct {
	// contains filtered or unexported fields
}

KeyState contains all of the evaluation state of RecursiveComputer for a given key. If evaluation has not yet finished, it stores the list of keys that are currently blocked on it (i.e., its reverse dependencies). When evaluated, it stores the value associated with the key or any error that occurred computing it.

type KeysReaderForTesting ¶

type KeysReaderForTesting = model_parser.MessageObjectReader[object.LocalReference, []*model_evaluation_pb.Keys]

KeysReaderForTesting is used to generate mocks that are used by RecursiveComputer's unit tests.

type LookupResultReaderForTesting ¶

type LookupResultReaderForTesting = model_parser.MessageObjectReader[object.LocalReference, *model_evaluation_cache_pb.LookupResult]

LookupResultReaderForTesting is used to generate mocks that are used by RecursiveComputer's unit tests.

type NestedError ¶

type NestedError[TReference object.BasicReference, TMetadata model_core.ReferenceMetadata] struct {
	KeyState *KeyState[TReference, TMetadata]
	Err      error
}

NestedError is used to wrap errors that occurred while evaluating a dependency of a given key. The key of the dependency is included, meaning that repeated unwrapping can be used to obtain a stack trace.

func (e NestedError[TReference, TMetadata]) Error() string

type ObjectManagerForTesting ¶

type ObjectManagerForTesting = model_core.ObjectManager[object.LocalReference, model_core.ReferenceMetadata]

ObjectManagerForTesting is used to generate mocks that are used by RecursiveComputer's unit tests.

type ProtoEvaluationReaderForTesting ¶

type ProtoEvaluationReaderForTesting = model_parser.MessageObjectReader[object.LocalReference, *model_evaluation_pb.Evaluation]

ProtoEvaluationReaderForTesting is used to generate mocks that are used by RecursiveComputer's unit tests.

type RecursiveComputer ¶

type RecursiveComputer[TReference object.BasicReference, TMetadata model_core.ReferenceMetadata] struct {
	// contains filtered or unexported fields
}

RecursiveComputer can be used to compute values, taking dependencies between keys into account.

Whenever the computation function requests the value for a key that has not been computed before, the key of the dependency is placed in a queue. Once the values of all previously missing dependencies are available, computation of the original key is restarted. This process repeates itself until all requested keys are exhausted.

func NewRecursiveComputer[TReference object.BasicReference, TMetadata model_core.ReferenceMetadata](
	base Computer[TReference, TMetadata],
	evaluationQueuePicker RecursiveComputerEvaluationQueuePicker[TReference, TMetadata],
	referenceFormat object.ReferenceFormat,
	objectManager model_core.ObjectManager[TReference, TMetadata],
	tagStore model_tag.BoundStore[TReference],
	actionTagKeyReference object.LocalReference,
	evaluationReader model_parser.MessageObjectReader[TReference, *model_evaluation_pb.Evaluation],
	lookupResultReader model_parser.MessageObjectReader[TReference, *model_evaluation_cache_pb.LookupResult],
	keysReader model_parser.MessageObjectReader[TReference, []*model_evaluation_pb.Keys],
	cacheDeterministicEncoder model_encoding.DeterministicBinaryEncoder,
	cacheKeyedEncoder model_encoding.KeyedBinaryEncoder,
	clock clock.Clock,
) *RecursiveComputer[TReference, TMetadata]

func (rc *RecursiveComputer[TReference, TMetadata]) GetEvaluations(ctx context.Context, keyStates []*KeyState[TReference, TMetadata]) (model_core.PatchedMessage[[]*model_evaluation_pb.Evaluations, TMetadata], error)

func (rc *RecursiveComputer[TReference, TMetadata]) GetKeyStateKeyMessage(ctx context.Context, ks *KeyState[TReference, TMetadata]) (model_core.TopLevelMessage[*anypb.Any, TReference], error)

func (rc *RecursiveComputer[TReference, TMetadata]) GetOrCreateKeyState(key model_core.TopLevelMessage[*anypb.Any, TReference]) (*KeyState[TReference, TMetadata], error)

func (rc *RecursiveComputer[TReference, TMetadata]) GetProgress(ctx context.Context) (model_core.PatchedMessage[*model_evaluation_pb.Progress, TMetadata], error)

func (rc *RecursiveComputer[TReference, TMetadata]) GracefullyStopUploading()

func (rc *RecursiveComputer[TReference, TMetadata]) OverrideKeyState(keyReference object.LocalReference, value model_core.TopLevelMessage[*anypb.Any, TReference]) error

func (rc *RecursiveComputer[TReference, TMetadata]) ProcessNextEvaluatableKey(ctx context.Context, rceq *RecursiveComputerEvaluationQueue[TReference, TMetadata]) bool

func (rc *RecursiveComputer[TReference, TMetadata]) ProcessNextUploadableKey(ctx context.Context) (bool, error)

func (rc *RecursiveComputer[TReference, TMetadata]) WaitForEvaluation(ctx context.Context, ks *KeyState[TReference, TMetadata]) error

type RecursiveComputerEvaluationQueue ¶

type RecursiveComputerEvaluationQueue[TReference object.BasicReference, TMetadata model_core.ReferenceMetadata] struct {
	// contains filtered or unexported fields
}

RecursiveComputerEvaluationQueue represents a queue of evaluation keys that are currently not blocked and are ready to be evaluated.

Instances of RecursiveComputer can make use of multiple evaluation queues. This can be used to enforce that different types of keys are evaluated with different amounts of concurrency. For example, keys that are CPU intensive to evaluate can be executed with a concurrency proportional to the number of locally available CPU cores, while keys that perform long-running network requests can use a higher amount of concurrency.

func NewRecursiveComputerEvaluationQueue[TReference object.BasicReference, TMetadata model_core.ReferenceMetadata]() *RecursiveComputerEvaluationQueue[TReference, TMetadata]

type RecursiveComputerEvaluationQueuePicker ¶

type RecursiveComputerEvaluationQueuePicker[TReference object.BasicReference, TMetadata model_core.ReferenceMetadata] interface {
	PickQueue(typeURL string) *RecursiveComputerEvaluationQueue[TReference, TMetadata]
}

RecursiveComputerEvaluationQueuePicker is used by RecursiveComputer to pick a RecursiveComputerEvaluationQueue to which a given key should be assigned.

type RecursiveComputerEvaluationQueues ¶

type RecursiveComputerEvaluationQueues[TReference object.BasicReference, TMetadata model_core.ReferenceMetadata] interface {
	RecursiveComputerEvaluationQueuePicker[TReference, TMetadata]

	ProcessAllEvaluatableKeys(group program.Group, computer *RecursiveComputer[TReference, TMetadata])
}

RecursiveComputerEvaluationQueues represents a set of queues that RecursiveComputer may use to schedule the evaluation of keys.

Simple implementations may place all keys in a single queue, but this has the disadvantage that all work is limited by the same concurrency limit. This may be sufficient if all work is CPU intensive, but may lead to low utilization if some work calls into remote services and may block for large amounts of time.

type RecursiveComputerEvaluationQueuesFactory ¶

type RecursiveComputerEvaluationQueuesFactory[TReference object.BasicReference, TMetadata model_core.ReferenceMetadata] interface {
	NewQueues() RecursiveComputerEvaluationQueues[TReference, TMetadata]
}

RecursiveComputerEvaluationQueuesFactory is invoked by Executor to create the queues that are necessary to schedule the evaluation of keys.

func NewSimpleRecursiveComputerEvaluationQueuesFactory[TReference object.BasicReference, TMetadata model_core.ReferenceMetadata](concurrency uint32) RecursiveComputerEvaluationQueuesFactory[TReference, TMetadata]