cache

Documentation

Overview

Package cache provides a key-value cache abstraction with a built-in in-memory store. Modelled on Laravel's Cache facade.

The Store interface is small enough to back with Redis, Memcached, or a database — those drivers live in separate sub-packages so the core module has zero extra dependencies.

Usage:

c := cache.NewMemory()
c.Put(ctx, "user:1", []byte("Ada"), 5*time.Minute)
v, ok, _ := c.Get(ctx, "user:1")
c.Forget(ctx, "user:1")

Helper:

v, err := cache.Remember(ctx, c, "users:list", time.Minute, func() ([]byte, error) {
    return fetchAndSerializeUsers()
})

Index

• Variables
• func Pull(ctx context.Context, s Store, key string) ([]byte, bool, error)
• func Remember(ctx context.Context, s Store, key string, ttl time.Duration, ...) ([]byte, error)
• type Memory
  • func NewMemory() *Memory
  • func (m *Memory) Close()
  • func (m *Memory) Flush(_ context.Context) error
  • func (m *Memory) Forget(_ context.Context, key string) error
  • func (m *Memory) Get(_ context.Context, key string) ([]byte, bool, error)
  • func (m *Memory) Has(ctx context.Context, key string) (bool, error)
  • func (m *Memory) Put(_ context.Context, key string, value []byte, ttl time.Duration) error
• type Store

Variables

var ErrMiss = errors.New("cache: key not found")

ErrMiss is returned by Get-shaped APIs that signal absence with an error. The basic Store interface uses (value, ok, error) instead, so ErrMiss is mostly informational for higher layers.

Functions

func Pull

func Pull(ctx context.Context, s Store, key string) ([]byte, bool, error)

Pull reads a key and removes it atomically. Returns (nil, false, nil) on miss.

func Remember

func Remember(ctx context.Context, s Store, key string, ttl time.Duration, fn func() ([]byte, error)) ([]byte, error)

Remember returns the value for key if present, otherwise calls fn, stores the result with ttl, and returns it. The classic "cache-aside" pattern.

users, err := cache.Remember(ctx, store, "users:list", time.Minute,
    func() ([]byte, error) { return json.Marshal(listUsers()) })

Types

type Memory

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

Memory is a process-local Store backed by a sync.RWMutex map. Safe for concurrent use; expiry is lazy (checked on Get/Has) with a background sweeper to keep the map from growing unbounded.

func NewMemory

func NewMemory() *Memory

NewMemory returns a fresh in-memory cache. A goroutine periodically purges expired keys; call Close() when discarding the cache to stop it.

func (*Memory) Close

func (m *Memory) Close()

Close stops the background sweeper. Subsequent operations remain safe but expired entries will only be evicted on access.

func (*Memory) Flush

func (m *Memory) Flush(_ context.Context) error

func (*Memory) Forget

func (m *Memory) Forget(_ context.Context, key string) error

func (*Memory) Get

func (m *Memory) Get(_ context.Context, key string) ([]byte, bool, error)

func (*Memory) Has

func (m *Memory) Has(ctx context.Context, key string) (bool, error)

func (*Memory) Put

func (m *Memory) Put(_ context.Context, key string, value []byte, ttl time.Duration) error

type Store

type Store interface {
	// Get returns the value, whether the key existed, and any driver
	// error. An expired entry behaves like a miss (ok=false, err=nil).
	Get(ctx context.Context, key string) ([]byte, bool, error)
	// Put stores value under key with the given TTL. ttl==0 means store
	// without expiry (until explicit Forget / Flush).
	Put(ctx context.Context, key string, value []byte, ttl time.Duration) error
	// Forget removes the key (no error if missing).
	Forget(ctx context.Context, key string) error
	// Flush wipes everything.
	Flush(ctx context.Context) error
	// Has reports whether the key exists and is not expired.
	Has(ctx context.Context, key string) (bool, error)
}

Store is the minimum surface a cache driver must implement.

All methods take a context so callers can cancel slow remote stores. The in-memory implementation ignores the context value but still respects the deadline via the (rare) blocking codepaths.