gocache

You can attach tags to cached items using store.WithTags([]string{...}) during the Set operation. This allows you to invalidate groups of related items simultaneously using marshal.Invalidate with store.WithInvalidateTags([]string{...}).

// Set an item with a tag
err = marshal.Set(ctx, key, value, store.WithTags([]string{"book"}))

// Remove all items that have the "book" tag
err := marshal.Invalidate(ctx, store.WithInvalidateTags([]string{"book"}))

For stores that only support string or byte slices (like Redis), use the marshaler service. It automatically handles the marshaling and unmarshaling of Go structs.

When calling .Get(), you must provide a pointer to the target struct as the third argument to unmarshal the data into.

// Initializes marshaler
marshal := marshaler.New(cacheManager)

key := BookQuery{Slug: "my-test-amazing-book"}
value := Book{ID: 1, Name: "My test amazing book", Slug: "my-test-amazing-book"}

// Set with marshaling
err = marshal.Set(ctx, key, value)

// Get with unmarshaling into a specific type
returnedValue, err := marshal.Get(ctx, key, new(Book))

When using gocache, import the core cache package and your chosen store package. For example, to use Redis:

import (
	"github.com/eko/gocache/lib/v4/cache"
	"github.com/eko/gocache/store/redis/v4"
)

A Chain cache allows you to layer multiple caches. When a key is requested, it checks the caches in the order they were provided. If a value is found in a later cache (e.g., Redis), it is automatically set back into the preceding caches (e.g., Ristretto/Memory) in the background.

Note: A Chain cache owns a goroutine for background updates. You must call Close() to release the goroutine and ensure pending values are set.

// Initialize stores
ristrettoStore := ristretto_store.NewRistretto(ristrettoCache)
redisStore := redis_store.NewRedis(redisClient, store.WithExpiration(5*time.Second))

// Initialize chained cache
cacheManager := cache.NewChain[any](
    cache.New[any](ristrettoStore),
    cache.New[any](redisStore),
)
defer cacheManager.Close()

A Loadable cache uses a provided loadFunction to retrieve data if it is missing from the cache. Once the function retrieves the data, the cache automatically populates the underlying store(s) with the result.

Note: Like Chain, Loadable caches run background processes for updates; call Close() to clean up.

You can wrap a Chain cache inside a Loadable cache to ensure data is backfilled across all layers of the chain.

// Initialize a load function
loadFunction := func(ctx context.Context, key any) (*Book, error) {
    // ... retrieve value from custom source
    return &Book{ID: 1, Name: "My test amazing book"}, nil
}

// Initialize loadable cache
cacheManager := cache.NewLoadable[*Book](
	loadFunction,
	cache.New[*Book](redisStore),
)
defer cacheManager.Close()

You can wrap a cache with cache.NewMetric[T] to record cache hits, misses, and other statistics using a metric provider (e.g., Prometheus).

// Initializes Prometheus metrics service
promMetrics := metrics.NewPrometheus("my-test-app")

// Initialize metric cache
cacheManager := cache.NewMetric[any](
	promMetrics,
	cache.New[any](redisStore),
)

The OptionsPegasus struct defines the connection and table settings for the Pegasus store. It embeds lib_store.Options for standard cache configuration.

Key fields:

• MetaServers: A slice of strings containing the Pegasus meta server addresses (Required).
• TableName: The name of the Pegasus table to use. Defaults to gocache_pegasus if empty.
• TablePartitionNum: Number of partitions for the table. Defaults to 4.
• TableScanNum: The batch size used during scanning operations (like Clear). Defaults to 100.

Gocache supports various built-in stores. You can install them by running go get for the corresponding package path. Available stores include:

• github.com/eko/gocache/store/bigcache/v4 (bigcache)
• github.com/eko/gocache/store/freecache/v4 (freecache)
• github.com/eko/gocache/store/go_cache/v4 (go-cache)
• github.com/eko/gocache/store/hazelcast/v4 (hazelcast)
• github.com/eko/gocache/store/memcache/v4 (memcache)
• github.com/eko/gocache/store/pegasus/v4 (pegasus)
• github.com/eko/gocache/store/redis/v4 (redis)
• github.com/eko/gocache/store/rediscluster/v4 (rediscluster)
• github.com/eko/gocache/store/rueidis/v4 (rueidis)
• github.com/eko/gocache/store/ristretto/v4 (ristretto)