mace

README

Mace

Fast caching data objects fast within golang application

Mace saves time setting up separate server. It is fast because its in-process and does not have serialization, deserialization costs.

How to install

  go get github.com/djinn/mace

Example

package main

import (
  "fmt"
  "time"

  "github.com/djinn/mace"
)

// Key in mace is always string type
// Value can be declared to be of arbitrary type
// Keys & values in cache2go can be off arbitrary types, e.g. a struct.

type ProductType struct {
  ProductId   int64
  ProductName string
  Variants    string //declared string to keep it simple
  Inventory   []uint
}

func main() {
  //Declare cache bucket
  cache := mace.Mace("product")

  // Declare cache object with alive value. Lets say 10 seconds
  product := ProductType{
    522013,
    "Nike Flyknit",
    "black and blue",
    []uint{1, 2, 3},
  }
  cache.Set("522013", &product, 5*time.Millisecond)

  // Let's retrieve the item from the cache.
  res, err := cache.Get("522013")
  if err == nil {
    fmt.Println("Found value in key:", res.Data().(*ProductType))
  } else {
    fmt.Println("Error retrieving value from cache:", err)
  }

  // Wait for the item to expire in cache.
  time.Sleep(6 * time.Second)
  res, err = cache.Get("522013")
  if err != nil {
    fmt.Println("Item is not cached (anymore).")
  }
  val := "string"
  // Add another item that never expires.
  cache.Set("471983", &val, 0)

  // mace supports a few handy callbacks and loading mechanisms.
  cache.SetOnDeleteItem(func(e *mace.MaceItem) {
    fmt.Println("Deleting:", e.Key(), *e.Data().(*string))
  })

  // Remove the item from the cache.
  cache.Delete("471983")

  // And wipe the entire cache table.
  cache.Flush()
}

Key Advantages

• Fast, because it exists within same process space
• Does not have expensive JSON serialization, deserialization
• Supports Native slices, lists, maps, structs and custom types
• Expiration can be set on each key
• Ability to setup 'add item' and 'deleted item' events
• Load item event to allow fetching uncached items

Mace does not fit where

• key store is shared in a cluster
• item specific events need to be generated
• Where keys are not string

Documentation

Index

• Variables
• type MaceBucket
  • func Mace(bucket_name string) *MaceBucket
  • func MaceAccessMax(bucket_name string, accessMax int) *MaceBucket
  • func (bucket *MaceBucket) Count() int
  • func (bucket *MaceBucket) Delete(key string) (*MaceItem, error)
  • func (bucket *MaceBucket) Exists(key string) bool
  • func (bucket *MaceBucket) Flush()
  • func (bucket *MaceBucket) Get(key string) (*MaceItem, error)
  • func (bucket *MaceBucket) KeepAlive(key string) error
  • func (bucket *MaceBucket) Name() string
  • func (bucket *MaceBucket) Set(key string, data interface{}, alive time.Duration) *MaceItem
  • func (bucket *MaceBucket) SetDataLoader(f func(string) *MaceItem)
  • func (bucket *MaceBucket) SetLogger(logger *log.Logger)
  • func (bucket *MaceBucket) SetOnAddItem(f func(*MaceItem))
  • func (bucket *MaceBucket) SetOnDeleteItem(f func(*MaceItem))
• type MaceItem
  • func NewMaceItem(key string, val interface{}, aliveUntil time.Duration) *MaceItem
  • func (item *MaceItem) Access() time.Time
  • func (item *MaceItem) AccessCount() int
  • func (item *MaceItem) Alive() time.Duration
  • func (item *MaceItem) Created() time.Time
  • func (item *MaceItem) Data() interface{}
  • func (item *MaceItem) KeepAlive()
  • func (item *MaceItem) Key() string

Variables

var (
	ErrKeyNotFound           = errors.New("Key not found in cache")
	ErrKeyNotFoundOrLoadable = errors.New("Key not found and could not be loaded into cache")
)

Types

type MaceBucket

type MaceBucket struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

func Mace

func Mace(bucket_name string) *MaceBucket

func MaceAccessMax

func MaceAccessMax(bucket_name string, accessMax int) *MaceBucket

func (*MaceBucket) Count

func (bucket *MaceBucket) Count() int

func (*MaceBucket) Delete

func (bucket *MaceBucket) Delete(key string) (*MaceItem, error)

func (*MaceBucket) Exists

func (bucket *MaceBucket) Exists(key string) bool

func (*MaceBucket) Flush

func (bucket *MaceBucket) Flush()

func (*MaceBucket) Get

func (bucket *MaceBucket) Get(key string) (*MaceItem, error)

func (*MaceBucket) KeepAlive

func (bucket *MaceBucket) KeepAlive(key string) error

func (*MaceBucket) Name

func (bucket *MaceBucket) Name() string

func (*MaceBucket) Set

func (bucket *MaceBucket) Set(key string, data interface{},
	alive time.Duration) *MaceItem

func (*MaceBucket) SetDataLoader

func (bucket *MaceBucket) SetDataLoader(f func(string) *MaceItem)

func (*MaceBucket) SetLogger

func (bucket *MaceBucket) SetLogger(logger *log.Logger)

func (*MaceBucket) SetOnAddItem

func (bucket *MaceBucket) SetOnAddItem(f func(*MaceItem))

func (*MaceBucket) SetOnDeleteItem

func (bucket *MaceBucket) SetOnDeleteItem(f func(*MaceItem))

type MaceItem

type MaceItem struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

func NewMaceItem

func NewMaceItem(key string, val interface{}, aliveUntil time.Duration) *MaceItem

func (*MaceItem) Access

func (item *MaceItem) Access() time.Time

func (*MaceItem) AccessCount

func (item *MaceItem) AccessCount() int

func (*MaceItem) Alive

func (item *MaceItem) Alive() time.Duration

func (*MaceItem) Created

func (item *MaceItem) Created() time.Time

func (*MaceItem) Data

func (item *MaceItem) Data() interface{}

func (*MaceItem) KeepAlive

func (item *MaceItem) KeepAlive()

func (*MaceItem) Key

func (item *MaceItem) Key() string