csc

README

A small cache library on top of redigo utilizing Redis's server-assisted client side caching functionality

This library has been created with the main use-case being a web server, and thus http requests. The library includes two approaches to accomplish a server-assisted local cache for this use-case:

1. Caching per client using Tracking mode. Get a client for each request from a client pool. Each client handles its own cache storage. Meaning the storage has the same lifetime as the client and keys are not shared between the clients. If a client loses either of its connections (data and/or invalidation) to Redis, it's marked as failed and never reused since it is assumed to be out-of-sync.

2. Global cache using Broadcasting mode. Create a single broadcasting client that invalidates a global cache. Each request's cache client doesn't track keys but just gets from/sets to the local storage during Set/Get calls. If the broadcasting invalidation connection fails the global cache must be flushed.

Usage

// Broadcasting mode, the pool contains the global cache
pool, _ := csc.NewDefaultBroadcastingPool(PoolOptions{MaxEntries: 1000, RedisAddress: ":6379"})
defer pool.Close() // usually not needed since the pool lifetime is normally the same as the app

c, _ := pool.Get() // get a client on request start
defer c.Close() // close on request end

// an hour expire
c.Set("hello", []byte("world"), 3600)

// no expire (csc.NoExpire is just a const for 0)
c.Set("hello_no_exp", []byte("world"), csc.NoExpire)

// get just returns the []byte
data, _ := c.Get("hello")

c.Delete("hello")

Documentation

Index

• Constants
• Variables
• type BroadcastingPool
  • func NewBroadcastingPool(rpool *redis.Pool, opts PoolOptions) (*BroadcastingPool, error)
  • func NewDefaultBroadcastingPool(opts PoolOptions) (*BroadcastingPool, error)
  • func (p *BroadcastingPool) Close() error
  • func (p *BroadcastingPool) Flush()
  • func (p *BroadcastingPool) Get() (*Client, error)
  • func (p *BroadcastingPool) Options() *PoolOptions
  • func (p *BroadcastingPool) Stats() Stats
• type Client
  • func (c *Client) Close() error
  • func (c *Client) Conn() redis.Conn
  • func (c *Client) Delete(keys ...string) error
  • func (c *Client) Flush()
  • func (c *Client) Get(key string) ([]byte, error)
  • func (c *Client) GetEntries(keys []string) ([]Entry, error)
  • func (c *Client) GetEntry(key string) (Entry, error)
  • func (c *Client) Set(key string, value []byte, expires int) error
  • func (c *Client) Stats() Stats
• type Entry
• type Pool
• type PoolOptions
• type Stats
• type TrackingPool
  • func NewTrackingPool(opts PoolOptions) *TrackingPool
  • func (p *TrackingPool) Close() error
  • func (p *TrackingPool) Get() (*Client, error)
  • func (p *TrackingPool) Options() *PoolOptions

Constants

const NoExpire = 0

Variables

var ErrClosed = errors.New("client is closed")

var ErrTooManyActiveClients = errors.New("too many active clients")

var Logger = log.New(os.Stdout, "csc ", log.Ldate|log.Lmicroseconds)

Types

type BroadcastingPool

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

func NewBroadcastingPool

func NewBroadcastingPool(rpool *redis.Pool, opts PoolOptions) (*BroadcastingPool, error)

creates a new broadcasting pool and starts the background jobs

func NewDefaultBroadcastingPool

func NewDefaultBroadcastingPool(opts PoolOptions) (*BroadcastingPool, error)

func (*BroadcastingPool) Close

func (p *BroadcastingPool) Close() error

func (*BroadcastingPool) Flush

func (p *BroadcastingPool) Flush()

func (*BroadcastingPool) Get

func (p *BroadcastingPool) Get() (*Client, error)

func (*BroadcastingPool) Options

func (p *BroadcastingPool) Options() *PoolOptions

func (*BroadcastingPool) Stats

func (p *BroadcastingPool) Stats() Stats

type Client

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

func (*Client) Close

func (c *Client) Close() error

func (*Client) Conn

func (c *Client) Conn() redis.Conn

func (*Client) Delete

func (c *Client) Delete(keys ...string) error

func (*Client) Flush

func (c *Client) Flush()

func (*Client) Get

func (c *Client) Get(key string) ([]byte, error)

func (*Client) GetEntries

func (c *Client) GetEntries(keys []string) ([]Entry, error)

todo(jhamren): if perf needs it, implement this properly with MGET

func (*Client) GetEntry

func (c *Client) GetEntry(key string) (Entry, error)

func (*Client) Set

func (c *Client) Set(key string, value []byte, expires int) error

func (*Client) Stats

func (c *Client) Stats() Stats

type Entry

type Entry struct {
	Data    []byte
	Expires time.Time
	Hit     bool
}

type Pool

type Pool interface {
	Get() (*Client, error)
	Close() error
	Options() *PoolOptions
	// contains filtered or unexported methods
}

type PoolOptions

type PoolOptions struct {
	RedisAddress  string
	RedisDatabase int
	MaxActive     int
	MaxIdle       int
	IdleTimeout   time.Duration
	Wait          bool
	// key prefix to add to keys. in broadcasting mode this is used to invalidate only keys with this prefix
	KeyPrefix  string
	MaxEntries int
}

type Stats

type Stats struct {
	Hits       uint64 `json:"hits"`
	Misses     uint64 `json:"misses"`
	Evictions  uint64 `json:"evictions"`
	Expired    uint64 `json:"expired"`
	NumEntries int    `json:"num_entries"`
}

type TrackingPool

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

func NewTrackingPool

func NewTrackingPool(opts PoolOptions) *TrackingPool

func (*TrackingPool) Close

func (p *TrackingPool) Close() error

closes connections of all clients in the free list

func (*TrackingPool) Get

func (p *TrackingPool) Get() (*Client, error)

func (*TrackingPool) Options

func (p *TrackingPool) Options() *PoolOptions