lazyslot

Documentation

Overview

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

The defining property of the implementation is that only one goroutine will block when refreshing such object, while all others will use a slightly stale cached copy.

Index

• type Fetcher
• type Slot
  • func (s *Slot) Get(c context.Context) (result Value, err error)
• type Value

Types

type Fetcher

type Fetcher func(c context.Context, prev Value) (Value, error)

Fetcher knows how to load a new value.

If it returns no errors, it MUST return non-nil Value.Value or Slot.Get will panic.

type Slot

type Slot struct {
	Fetcher    Fetcher       // used to actually load the value on demand
	Timeout    time.Duration // how long to allow to fetch, 15 sec by default.
	RetryDelay time.Duration // how long to wait before fetching after a failure, 5 sec by default
	// contains filtered or unexported fields
}

Slot holds a cached Value and refreshes it when it expires.

Only one goroutine will be busy refreshing, all others will see a slightly stale copy of the value during the refresh.

func (*Slot) Get

func (s *Slot) Get(c context.Context) (result Value, err error)

Get returns stored value if it is still fresh.

It may return slightly 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 Fetcher returns an error.

If there's an expired cached copy, and Fetcher 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 refetch errors bumps expiration time of the cached copy to RetryDelay seconds from now, effectively scheduling a retry at some later time. RetryDelay is 5 sec by default.

Panics if Fetcher doesn't produce a non-nil value and doesn't return an error. It must either return an error or an non-nil value.

type Value

type Value struct {
	// Value is whatever fetcher returned.
	Value interface{}
	// Expiration is time when this value expires and should be refetched.
	Expiration time.Time
}

Value is what's stored in a Slot. It is treated as immutable value.