memoize

Documentation

Overview

Package memoize supports memoizing the return values of functions with idempotent results that are expensive to compute.

The memoized result is returned again the next time the function is invoked. To prevent excessive memory use, the return values are only remembered for as long as they still have a user.

To use this package, build a store and use it to acquire handles with the Bind method.

Index

• type Function
• type Handle
  • func (h *Handle) Cached() interface{}
  • func (h *Handle) Get(ctx context.Context) interface{}
• type NoCopy
• type Store
  • func (s *Store) Bind(key interface{}, function Function) *Handle
  • func (s *Store) Cached(key interface{}) interface{}
  • func (s *Store) DebugOnlyIterate(f func(k, v interface{}))
  • func (s *Store) Find(key interface{}) *Handle
  • func (s *Store) Has(key interface{}) bool
  • func (s *Store) Stats() map[reflect.Type]int

Types

type Function

type Function func(ctx context.Context) interface{}

Function is the type for functions that can be memoized. The result must be a pointer.

type Handle

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

Handle is returned from a store when a key is bound to a function. It is then used to access the results of that function.

A Handle starts out in idle state, waiting for something to demand its evaluation. It then transitions into running state. While it's running, waiters tracks the number of Get calls waiting for a result, and the done channel is used to notify waiters of the next state transition. Once the evaluation finishes, value is set, state changes to completed, and done is closed, unblocking waiters. Alternatively, as Get calls are cancelled, they decrement waiters. If it drops to zero, the inner context is cancelled, computation is abandoned, and state resets to idle to start the process over again.

func (*Handle) Cached

func (h *Handle) Cached() interface{}

Cached returns the value associated with a handle.

It will never cause the value to be generated. It will return the cached value, if present.

func (*Handle) Get

func (h *Handle) Get(ctx context.Context) interface{}

Get returns the value associated with a handle.

If the value is not yet ready, the underlying function will be invoked. This activates the handle, and it will remember the value for as long as it exists. If ctx is cancelled, Get returns nil.

type NoCopy

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

NoCopy is a type with no public methods that will trigger a vet check if it is ever copied. You can embed this in any type intended to be used as a value. This helps avoid accidentally holding a copy of a value instead of the value itself.

type Store

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

Store binds keys to functions, returning handles that can be used to access the functions results.

func (*Store) Bind

func (s *Store) Bind(key interface{}, function Function) *Handle

Bind returns a handle for the given key and function.

Each call to bind will return the same handle if it is already bound. Bind will always return a valid handle, creating one if needed. Each key can only have one handle at any given time. The value will be held for as long as the handle is, once it has been generated. Bind does not cause the value to be generated.

func (*Store) Cached

func (s *Store) Cached(key interface{}) interface{}

Cached returns the value associated with a key.

It cannot cause the value to be generated. It will return the cached value, if present.

func (*Store) DebugOnlyIterate

func (s *Store) DebugOnlyIterate(f func(k, v interface{}))

DebugOnlyIterate iterates through all live cache entries and calls f on them. It should only be used for debugging purposes.

func (*Store) Find

func (s *Store) Find(key interface{}) *Handle

Find returns the handle associated with a key, if it is bound.

It cannot cause a new handle to be generated, and thus may return nil.

func (*Store) Has

func (s *Store) Has(key interface{}) bool

Has returns true if they key is currently valid for this store.

func (*Store) Stats

func (s *Store) Stats() map[reflect.Type]int

Stats returns the number of each type of value in the store.