Documentation ¶
Index ¶
- Variables
- func Execute[K comparable, V any](ctx context.Context, executionKey K, ...) (TypedOutcome[V], Extra)
- func FindOutcomes[K comparable, V any](ctx context.Context, executionKey K) map[K]TypedOutcome[V]
- func PopulateCache(ctx context.Context, entries map[interface{}]Outcome)
- type DestroyFn
- type Extra
- type Function
- type Outcome
- type TypedOutcome
Constants ¶
This section is empty.
Variables ¶
Functions ¶
func Execute ¶
func Execute[K comparable, V any]( ctx context.Context, executionKey K, memoizedFn func(context.Context) (V, error), ) (TypedOutcome[V], Extra)
Execute guarantees that the given memoizedFn will be invoked only once regardless of how many times Execute gets called with the same executionKey. All callers will receive the same result and error as the result of this call.
Note 1: this promise can only be kept if the given context has been initialized using WithCache before calling Execute.
Note 2: the provided key must be comparable and should not be of type string or any other built-in type to avoid collisions between packages using this context. Callers of Execute should define their own types for keys similar to the best practices for using context.WithValue.
Note 3: cancelling the given context allows caller to stop waiting for the result from the memoizedFn. However, the memoizedFn will still proceed till completion unless the root context given to WithCache was cancelled.
func FindOutcomes ¶ added in v1.0.3
func FindOutcomes[K comparable, V any](ctx context.Context, executionKey K) map[K]TypedOutcome[V]
FindOutcomes returns all Outcome that were memoized under the given executionKey type at the time findOutcomes was called. If a promise related to this executionKey type is still pending, the function will block and wait for it to complete to get its Outcome.
Note: this function can only return all memoized Outcome if the given context has been initialized using WithCache.
func PopulateCache ¶ added in v1.0.3
PopulateCache will put the given entries into this cache. The key of such entries should be the executionKey that would be used to call execute. The value should be the Outcome that you want to map to this executionKey.
Note: the given entries can only be populated in the cache if the input context has been initialized using WithCache.
Types ¶
type DestroyFn ¶
type DestroyFn func()
func WithCache ¶
WithCache returns a new context.Context that holds a reference to a cache for memoized functions. This is meant to be a request-level cache that will automatically get garbage-collected at the end of an API request when the context itself is garbage-collected.
WithCache must be called near the start of an API request handling before being any memoized functions get executed in child goroutines.
The given context will be used as the root context of this cache. If it gets cancelled, all pending memoized executions will be abandoned. On the other hand, the context given to Execute won't affect pending executions. Child goroutines can cancel the context given to Execute to stop waiting for the result from the memoized function, which will still proceed till completion.
Note: the return DestroyFn must be deferred to minimize memory leaks.
type Extra ¶ added in v1.0.3
type Extra struct { // IsMemoized indicates if the outcome was memoized. IsMemoized bool // IsExecuted indicates if the outcome came from actual execution or // was pre-populated in the cache. IsExecuted bool }
Extra includes additional details about the returned outcome.
type Function ¶
Function is the type of function that can be memoized.
The argument must not materially affect the result of the function in ways that are not captured by the promise's key, since if promise.get is called twice concurrently, with the same (implicit) key but different arguments, the Function is called once and only once but its result must be suitable for both callers.
type Outcome ¶ added in v1.0.3
type Outcome struct { Value interface{} Err error }
Outcome is the outcome of executing a memoized function.
type TypedOutcome ¶ added in v1.0.4
TypedOutcome ...
func (TypedOutcome[V]) ResultOrDefault ¶ added in v1.0.5
func (o TypedOutcome[V]) ResultOrDefault(defaultResult V) V
ResultOrDefault returns the final result if there's no error or the default result if there's an error.