cache

README

Cache

Cache is a simple dependency free cache package with the ability to add new storage methods by implementing a new store.

This cache will run as many stores as needed and can run more than one instance at a time. You can access and maintain the stores individually per cache instance. Each cache will run a trimming function which calls the trim method implemented by each store to remove old items. The cache will also shut down gracefully. You can shut down all cache instances or a single instance.

This package supports the last 2 stable go versions.

• Install
• Stores
• Implementing
  • Cache Options
  • Accessing Stores
  • Direct Store Maintenance
  • Stopping

Install

$ go get github.com/tmstorm/cache

Stores

• Mem (In-memory)
• disk (On disk file store)

Implementing

Select and initiate each store you want to run in the cache.

[!NOTE] The Options for each store will vary depending on the store.

import "github.com/tmstorm/stores/mem"

func main() {
  ...
  store := mem.New(&mem.Store{
    // Every store should implement a MaxAge to be used for trimming old cache items.
    MaxAge: 1800,
  })
  ...
}

[!NOTE] MaxAge is measured in seconds so a value of 1800 would be 30 minutes

Initialize a new cache.

import (
  "github.com/tmstorm/cache"
)
func main() {
  ...
  c := cache.New(&cache.Options{
    TrimTime: 900,
    Stores: cache.MakeStores(store),
  })
  ...
}

Start the cache.

func main() {
  ...
  err := c.Start()
  if err != nil {
    log.Panicf("Cache instance could not be started: %v", err)
  }
  ...
}

Cache Options

Option	Default	Description
TrimTime	1800s (30m)	Used by the internal trim method to decide when the trim method for each store should be ran.
Stores	nil	Used be the current cache to access the store or stores used to save items

Accessing Stores

Once you have the cache started you can access the store. You will need to call the store to get the store's writer.

func main() {
  ...
  m := mem.Get(store)
  ...
}

Now you can access the store's writer methods.

func main() {
  ...
  key := "foo"
  value := "bar"
  overwrite := false

  // Get in-memory store
  m := mem.Get(store)

  // Write key-value pair
  err := m.Write(key, []byte(value), overwrite)
  if err != nil {
    fmt.Println(err)
  }

  // Read value with given key
  v, err := m.Read(key)
  if err != nil {
    fmt.Println(err)
  }

  // Delete key-value pair
  m.Remove(key)
  ...
}

Direct Store Maintenance

If you would like to trim or purge a store directly you can do so by calling their methods directly.

func main() {
  ...
  // Runs the stores trim method for removing old items
  m.Trim()

  // Runs the stores purge method to remove all items
  m.Purge()
  ...
}

Stopping

When you want to stop the cache there are two ways to do this. You can either stop all instances or a single cache instance.

To stop a single cache instance.

func main() {
  ...
  err := cache.StopCacheInstance(c.CacheNum)
  if err != nil {
    log.Println(err)
  }
  ...
}

To stop all running cache instances.

func main() {
  ...
  err := cache.StopAll()
  if err != nil {
    log.Println(err)
  }
  ...
}

Documentation

Overview

Package cache provides a dependency free store based cache with the ability to add new storage methods by implementing a new store.

Index

• Variables
• func StopAll() error
• func StopCacheInstance(cn int) error
• type MaxAge
• type Options
  • func New(o *Options) *Options
  • func (o *Options) Start() error
• type Store
• type Stores
  • func MakeStores(stores ...Store) Stores

Variables

var DefaultMaxAge = MaxAge(1800)

DefaultMaxAge is used to define the MaxAge if one is not set for an individual store. This needs to be implemented at the store level on initialization.

Functions

func StopAll

func StopAll() error

StopAll gracefully closes the all cache instances. It should stop the trim() worker. Purge the cache and remove the root directory. Reset caches to an empty map.

func StopCacheInstance

func StopCacheInstance(cn int) error

StopCacheInstance gracefully closes the specified cache instances. It should stop the trim() worker. Purge the cache by calling purge(). Remove the cache from the active Caches map.

Types

type MaxAge

type MaxAge time.Duration

MaxAge Defines the maximum allowed age of items stored in the cache measured in seconds. MaxAge = 1800 would set the MaxAge for all files to 30 minutes. This needs to be implemented for each store and used with the store specific Purge() method

type Options

type Options struct {
	// CacheNum is used to call which cache the user wants to use.
	// This is set when the cache instance is started and should be saved to access the cache later.
	CacheNum int

	// Stores is used to access the current caches active stores
	Stores Stores

	// TrimTime Defines the interval at which trim() calls the store specified Trim() method
	// to check the MaxAge of items the store.
	// TrimTime = 900 would set TrimTime to 15 minutes
	TrimTime time.Duration
	// contains filtered or unexported fields
}

Options sets an individual caches options

func New

func New(o *Options) *Options

New returns a new cache instance for use using the options struct. If no options are passed in or any are omitted the defaults will be applied.

func (*Options) Start

func (o *Options) Start() error

Start initiates a new cache instance. It needs to be initialized by New() It should start trim() as a goroutine for each store to maintain the cache size.

type Store

type Store interface {
	Type() string
	Trim()
	Purge() error
}

Store must be implemented for each store This is used to integrate into the cache and provide access to starting, stopping, and internal cache maintenance. a writer will still need to be implemented for each cache type.

type Stores

type Stores map[string]Store

Stores are used to access all the available stores

func MakeStores

func MakeStores(stores ...Store) Stores

MakeStores makes the stores after they have been initialized and are ready to be added to the cache