objcache

Documentation

Overview

Package objcache transcodes arbitrary Go types to bytes and stores them in a cache reducing GC.

A Cache can be either in memory or a persistent one. Cache adapters are available for bigcache or Redis. To enable the cache adapter use build tags "bigcache" or "redis" or "csall". More cache adapters might follow.

Use case: Caching millions of Go types as a byte slice reduces the pressure to the GC.

For more details regarding bigcache: https://godoc.org/github.com/allegro/bigcache

Index

• func MakeBinary() binary
• type Codecer
• type Decoder
• type Encoder
• type LRUOptions
• type NewStorageFn
  • func NewBlackHoleClient[K comparable](optionalTestErr error) NewStorageFn[K]
  • func NewLRU[K comparable](o *LRUOptions[K]) NewStorageFn[K]
• type Service
  • func NewService[K comparable](level1, level2 NewStorageFn[K], so *ServiceOptions) (_ *Service[K], err error)
  • func (tr *Service[K]) Close() error
  • func (tr *Service[K]) Delete(ctx context.Context, key ...K) error
  • func (tr *Service[K]) Get(ctx context.Context, key K, dst any) (err error)
  • func (tr *Service[K]) GetMulti(ctx context.Context, keys []K, dst []any) (err error)
  • func (tr *Service[K]) Set(ctx context.Context, key K, src any, expires time.Duration) error
  • func (tr *Service[K]) SetMulti(ctx context.Context, keys []K, src []any, expires []time.Duration) error
  • func (tr *Service[K]) Truncate(ctx context.Context) (err error)
• type ServiceOptions
• type Storager
  • func NewCacheSimpleInmemory[K comparable]() (Storager[K], error)

Functions

func MakeBinary

func MakeBinary() binary

MakeBinary creates a binary type for using in Set/Get functions when the code needs a `set` algorithm. For example checking if a JWT exists in the blockList. Function IsValid returns true if the key exists.

Types

type Codecer

type Codecer interface {
	NewEncoder(io.Writer) Encoder
	NewDecoder(io.Reader) Decoder
}

Codecer defines the functions needed to create a new Encoder or Decoder

type Decoder

type Decoder interface {
	Decode(dst any) error
}

Decoder defines how to decode a byte slice into variable dst. Please see option function WithEncoder() for details how to get the byte slice.

type Encoder

type Encoder interface {
	Encode(src any) error
}

Encoder defines how to Encode a type represented by variable src into a byte slice. Encoders must write their data into an io.Writer defined in option function WithEncoder().

type LRUOptions

type LRUOptions[K comparable] struct {
	Capacity           int64 // default 5000 objects
	TrackBySize        bool
	TrackByObjectCount bool // default
	LRUCache           *lru.Cache[K]
}

LRUOptions allows to track the cache items either by object count or total size in bytes. If tracking by `TrackBySize` gets enabled then `Capacity` must have the value in bytes. Default 64MB.

type NewStorageFn

type NewStorageFn[K comparable] func() (Storager[K], error)

func NewBlackHoleClient

func NewBlackHoleClient[K comparable](optionalTestErr error) NewStorageFn[K]

NewBlackHoleClient creates a black hole client for testing with the ability to return errors.

func NewLRU

func NewLRU[K comparable](o *LRUOptions[K]) NewStorageFn[K]

NewLRU creates a new LRU Storage. Expirations are not supported. Argument `o` can be nil, if so default values get applied.

type Service

type Service[K comparable] struct {
	// contains filtered or unexported fields
}

Service handles the encoding, decoding and caching.

func NewService

func NewService[K comparable](level1, level2 NewStorageFn[K], so *ServiceOptions) (_ *Service[K], err error)

NewService creates a new cache service. Arguments level1 and level2 define the cache level. For example level1 should be an LRU or another in-memory cache while level2 should be accessed via network. Only level2 is requred while level1 can be nil.

func (*Service[K]) Close

func (tr *Service[K]) Close() error

Close closes the underlying storage engines.

func (*Service[K]) Delete

func (tr *Service[K]) Delete(ctx context.Context, key ...K) error

Delete removes keys from the storage.

func (*Service[K]) Get

func (tr *Service[K]) Get(ctx context.Context, key K, dst any) (err error)

Get looks up the key and parses the raw data into the destination pointer `dst`. If `dst` implements interface

type unmarshaler interface {
	Unmarshal([]byte) error
}

the Unmarshal gets called (or one of the interface from package `encoding`). This type check has precedence before the decoder. You have to check yourself if the returned error is of type NotFound or of any other source. Every caching type defines its own NotFound error. If dst has no pointer property, no error gets returned, instead the passed value stays empty.

func (*Service[K]) GetMulti

func (tr *Service[K]) GetMulti(ctx context.Context, keys []K, dst []any) (err error)

GetMulti allows a cache backend to retrieve several values at once. Same decoding logic applies as when calling `Get`.

func (*Service[K]) Set

func (tr *Service[K]) Set(ctx context.Context, key K, src any, expires time.Duration) error

Set puts the item in the cache. `src` gets either encoded using the previously applied encoder OR `src` gets checked if it implements interface

type marshaler interface {
	Marshal() ([]byte, error)
}

and calls `Marshal`. (also checks for the interfaces in package "encoding"). Checking for marshaler has precedence. Useful with protobuf.

func (*Service[K]) SetMulti

func (tr *Service[K]) SetMulti(ctx context.Context, keys []K, src []any, expires []time.Duration) error

SetMulti allows a cache to write several entities at once. For example using Redis MSET. Same logic applies as when using `Set`.

func (*Service[K]) Truncate

func (tr *Service[K]) Truncate(ctx context.Context) (err error)

Truncate truncates all caches.

type ServiceOptions

type ServiceOptions struct {
	// Codec optionally encodes and decodes an object. The default "codec"
	// checks if a type implements Marshal() or Unmarshal() interface or any of
	// the two interfaces from package "encoding".
	Codec Codecer
	// PrimeObjects creates new encoder/decoder with a sync.Pool to reuse the
	// objects. Setting PrimeObjects causes the encoder/decode to prime the data
	// which means that no type information will be stored in the cache. If you
	// use gob you must use still gob.Register() your types. TL;DR: Skips type
	// information in the cache.
	PrimeObjects   []any
	DefaultExpires time.Duration
}

ServiceOptions used when creating a NewService.

type Storager

type Storager[K comparable] interface {
	Set(ctx context.Context, keys []K, values [][]byte, expirations []time.Duration) error
	// Get returns the bytes for given keys. The values slice must have the same
	// length as the keys slice. If one of the keys can't be found, its byte
	// slice must be `nil`.
	Get(ctx context.Context, keys []K) (values [][]byte, err error)
	Delete(ctx context.Context, keys []K) error
	Truncate(ctx context.Context) error
	Close() error
}

Storager defines a custom backend cache type to be used as underlying storage of the Service. Must be safe for concurrent usage. Caches which implement this interface can be enabled via build tag. The context depends if it is supported by a backend cache implementation. All keys and values have the same length. `expirations` is a list seconds with the same length as keys & values. A second entry defines when a key expires. If the entry is empty, the key does not expire.

func NewCacheSimpleInmemory

func NewCacheSimpleInmemory[K comparable]() (Storager[K], error)

NewCacheSimpleInmemory creates an in-memory map map[string]string as cache backend which supports expiration.