breadbox

Documentation

Overview

Package breadbox implements a caching scheme for globally shared objects that take significant time to refresh.

It is similar to lazyslot, but it has two distinct ways to retrieve from the cache:

• Get: accept staleness and have at most 1 goroutine block while refreshing (all other goroutines using this method will receive a slightly stale copy);
• GetFresh: refuse staleness and forcibly refresh the cache.

Index

• Constants
• type Breadbox
  • func (b *Breadbox) Get(ctx context.Context, maxStaleness time.Duration, refresher Refresher) (value any, err error)
  • func (b *Breadbox) GetFresh(ctx context.Context, refresher Refresher) (value any, err error)
• type Refresher

Constants

const (
	// The default delay between retries, if fetching fails and staleness is
	// acceptable.
	DefaultRetryDelay = 5 * time.Second
)

Types

type Breadbox

type Breadbox struct {
	RetryDelay time.Duration
	// contains filtered or unexported fields
}

func (*Breadbox) Get

func (b *Breadbox) Get(ctx context.Context, maxStaleness time.Duration,
	refresher Refresher) (value any, err error)

Get returns stored value if it is still fresh or refreshes it if it's stale.

May return a stale copy if some other goroutine is fetching a new copy now. If there's no cached copy at all, blocks until it is retrieved.

Returns an error only when there's no cached copy yet and Refresher returns an error.

If there's an existing cached copy, and Refresher returns an error when trying to refresh it, logs the error and returns the existing cached copy (which is stale at this point). We assume callers prefer stale copy over a hard error.

On refresh errors, delays the next retry by at least RetryDelay. RetryDelay is 5 sec by default.

The passed context is used for logging and for getting time.

func (*Breadbox) GetFresh

func (b *Breadbox) GetFresh(
	ctx context.Context, refresher Refresher) (value any, err error)

GetFresh forcibly refreshes the cache by refetching to get the latest value.

Returns an error only when there's no cached copy yet and Refresher returns an error.

If there's an existing cached copy, and Refresher returns an error when trying to refresh it, logs the error and returns the existing cached copy (which is stale at this point). We assume callers prefer stale copy over a hard error.

The passed context is used for logging and for getting time.

type Refresher

type Refresher func(ctx context.Context, prev any) (updated any, err error)