caching
packageAPI reference for the caching
package.
Imports
(4)Cache
Cache defines the generic caching contract.
type Cache interface
Example
cache := caching.NewInMemory[string](caching.WithTTL[string](5*time.Minute))
cache.Set(ctx, "key", "value", 0)
val, ok, err := cache.Get(ctx, "key")Methods
entry
entry holds a cached value with its expiry time.
type entry struct
Fields
| Name | Type | Description |
|---|---|---|
| value | T | |
| expiry | time.Time |
InMemoryCache
InMemoryCache is a thread-safe in-memory implementation of Cache.
type InMemoryCache struct
Example
cache := caching.NewInMemory[string]()
cache.Set(ctx, "greeting", "hello", time.Minute)Fields
| Name | Type | Description |
|---|---|---|
| mu | sync.RWMutex | |
| data | map[string]entry[T] | |
| defaultTTL | time.Duration | |
| maxEntries | int |
InMemoryOption
InMemoryOption configures an InMemoryCache.
type InMemoryOption func(*InMemoryCache[T])
NewInMemory
NewInMemory creates a new InMemoryCache with optional configuration.
Parameters
Returns
func NewInMemory[T any](opts ...InMemoryOption[T]) *InMemoryCache[T]
{
c := &InMemoryCache[T]{
data: make(map[string]entry[T]),
}
for _, opt := range opts {
opt(c)
}
return c
}Example
cache := caching.NewInMemory[string](
caching.WithTTL[string](time.Minute),
caching.WithMaxEntries[string](1000),
)WithTTL
WithTTL sets the default TTL for cache entries.
Parameters
Returns
func WithTTL[T any](d time.Duration) InMemoryOption[T]
{
return func(c *InMemoryCache[T]) { c.defaultTTL = d }
}WithMaxEntries
WithMaxEntries sets the maximum number of entries before eviction.
Parameters
Returns
func WithMaxEntries[T any](n int) InMemoryOption[T]
{
return func(c *InMemoryCache[T]) { c.maxEntries = n }
}DistributedCache
DistributedCache is a byte-level cache backend for distributed systems.
Implementations include Redis, Memcached, etc.
type DistributedCache interface
Methods
DistributedBridge
DistributedBridge adapts a DistributedCache to a typed Cache[T] using JSON.
type DistributedBridge struct
Fields
| Name | Type | Description |
|---|---|---|
| inner | DistributedCache |
NewDistributedBridge
NewDistributedBridge creates a typed cache bridge over a DistributedCache backend.
Parameters
Returns
func NewDistributedBridge[T any](backend DistributedCache) *DistributedBridge[T]
{
return &DistributedBridge[T]{inner: backend}
}DistributedInMemory
DistributedInMemory is an in-memory implementation of DistributedCache
suitable for testing and single-process scenarios.
type DistributedInMemory struct
Methods
Get implements DistributedCache.Get.
Parameters
Returns
func (*DistributedInMemory) Get(ctx context.Context, key string) ([]byte, bool, error)
{
m.mu.RLock()
e, ok := m.data[key]
m.mu.RUnlock()
if !ok {
return nil, false, nil
}
if !e.expiry.IsZero() && time.Now().After(e.expiry) {
m.mu.Lock()
delete(m.data, key)
m.mu.Unlock()
return nil, false, nil
}
return e.value, true, nil
}Set implements DistributedCache.Set.
Parameters
Returns
func (*DistributedInMemory) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
{
e := distributedEntry{value: value}
if ttl > 0 {
e.expiry = time.Now().Add(ttl)
} else if m.ttl > 0 {
e.expiry = time.Now().Add(m.ttl)
}
m.mu.Lock()
m.data[key] = e
m.mu.Unlock()
return nil
}Delete implements DistributedCache.Delete.
Parameters
Returns
func (*DistributedInMemory) Delete(ctx context.Context, key string) error
{
m.mu.Lock()
delete(m.data, key)
m.mu.Unlock()
return nil
}Fields
| Name | Type | Description |
|---|---|---|
| mu | sync.RWMutex | |
| data | map[string]distributedEntry | |
| ttl | time.Duration |
distributedEntry
type distributedEntry struct
Fields
| Name | Type | Description |
|---|---|---|
| value | []byte | |
| expiry | time.Time |
NewDistributedInMemory
NewDistributedInMemory creates a new in-memory distributed cache.
Parameters
Returns
func NewDistributedInMemory(opts ...DistributedInMemoryOption) *DistributedInMemory
{
c := &DistributedInMemory{
data: make(map[string]distributedEntry),
}
for _, opt := range opts {
opt(c)
}
return c
}DistributedInMemoryOption
DistributedInMemoryOption configures a DistributedInMemory cache.
type DistributedInMemoryOption func(*DistributedInMemory)
WithDistributedTTL
WithDistributedTTL sets the default TTL for entries.
Parameters
Returns
func WithDistributedTTL(d time.Duration) DistributedInMemoryOption
{
return func(c *DistributedInMemory) { c.ttl = d }
}