wcache

README

wcache

Implements in-memory cache with write-back strategy (a cache with expiration). An expiration callback(expireFn) will be called when record is expired.

Features

• Thread-safe.
• Per-key or global TTL.
• Can trigger a custom callback on key expiration(could be used as Pub/Sub with aggregation).
• Can trigger a custom callback on key collisions(e.g. for aggregating metrics). By default, will overwrite value.
• Graceful shutdown(using context). Will call expiration callback for all records, ignoring they TTL.

Install

go get github.com/vtopc/wcache

TODO

• Optional auto-extending expiration on Get and/or Set.

Similar projects

• https://github.com/mailgun/holster#expirecache

Documentation

Overview

Example

package main

import (
	"context"
	"time"

	"github.com/vtopc/wcache"
)

func main() {
	c := wcache.New(context.Background(), 100*time.Millisecond, wcache.PrintlnOnExpire)
	// put value with custom TTL:
	c.SetWithTTL("2", "to expire second", 200*time.Millisecond)
	// put value with default TTL:
	c.Set("1", "to expire first")

	time.Sleep(300 * time.Millisecond)

}

Output:

1: to expire first
2: to expire second

Index

• func AddInt64(old, new interface{}) (result interface{})
• func MaxInt64(old, new interface{}) (result interface{})
• func NoopExpire(key string, value interface{})
• func PrintlnOnExpire(key string, value interface{})
• type Cache
  • func New(ctx context.Context, defaultTTL time.Duration, expireFn ExpireFn) *Cache
  • func (c *Cache) Delete(key string)
  • func (c *Cache) Done() <-chan struct{}
  • func (c *Cache) Get(key string) (value interface{}, found bool)
  • func (c *Cache) Set(key string, value interface{})
  • func (c *Cache) SetWithTTL(key string, value interface{}, ttl time.Duration)
• type CompareFn
• type ExpireFn
  • func ChanExpire(ch chan<- KeyValue) ExpireFn
• type KeyValue

Examples

• Package
• Cache.Done
• CompareFn

Functions

func AddInt64

func AddInt64(old, new interface{}) (result interface{})

AddInt64 a CompareFn typed function that will add new value to the old one and return as result

func MaxInt64

func MaxInt64(old, new interface{}) (result interface{})

MaxInt64 a CompareFn typed function that will return biggest value as result

func NoopExpire

func NoopExpire(key string, value interface{})

NoopExpire does nothing

func PrintlnOnExpire

func PrintlnOnExpire(key string, value interface{})

PrintOnExpire a dummy ExpireFn that will print key, value when record is expired

Types

type Cache

type Cache struct {

	// thread unsafe(TODO):
	CompareFn CompareFn
	// contains filtered or unexported fields
}

func New

func New(ctx context.Context, defaultTTL time.Duration, expireFn ExpireFn) *Cache

New creates fully functional cache.

ctx is used for shutdown.

func (*Cache) Delete

func (c *Cache) Delete(key string)

Delete deletes the value for a key.

func (*Cache) Done

func (c *Cache) Done() <-chan struct{}

Done returns a channel that will be closed when work done(ExpireFn called for all records). This channel would not be closed if there are no records and context is not canceled(expired, etc.).

Example

package main

import (
	"context"
	"time"

	"github.com/vtopc/wcache"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	c := wcache.New(ctx, time.Hour, wcache.PrintlnOnExpire)

	c.Set("1", "my value") // should expire in an hour
	// but will expire after context cancellation
	cancel()
	<-c.Done()

}

Output:

1: my value

func (*Cache) Get

func (c *Cache) Get(key string) (value interface{}, found bool)

Get returns the value stored in the map for a key, or nil if no value is present. The found result indicates whether value was found in the cache.

func (*Cache) Set

func (c *Cache) Set(key string, value interface{})

SetWithTTL sets the value for a key with default TTL

func (*Cache) SetWithTTL

func (c *Cache) SetWithTTL(key string, value interface{}, ttl time.Duration)

SetWithTTL sets the value for a key.

type CompareFn

type CompareFn func(old, new interface{}) (result interface{})

CompareFn compares values on key collisions

Example

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/vtopc/wcache"
)

func main() {
	const key = "test"

	c := wcache.New(context.Background(), time.Hour, wcache.NoopExpire)
	c.CompareFn = wcache.MaxInt64

	c.Set(key, int64(1))
	c.Set(key, int64(2))

	v, _ := c.Get(key)
	fmt.Println(v)

}

Output:

2

type ExpireFn

type ExpireFn func(key string, value interface{})

ExpireFn a callback that will be called when record is expired

func ChanExpire

func ChanExpire(ch chan<- KeyValue) ExpireFn

ChanExpire returns a ExpireFn that will send key, value to the channel `ch` when record is expired

type KeyValue

type KeyValue struct {
	Key   string
	Value interface{}
}