jac

README

jac : just another cache

jac is a persistent in-memory key:value/store cache inspired by go-cache that is basically am augmented thread-safe collections of map[string]string with expiration time called buckets.
jac is suitable for application running on a single machine that need persistence and resistance towards system or application crashes. It achieved this by duplicating the data itself on the disk in a readable manner (optional) during execution and as a standard GOB once the application has closed. In this way it is possible to load a the latest cache state after an application restart or a system crash.
jac generates two files either during operation (.data) or for shutdown back-up (.rec). The former is a JSON text file that is sued to reload the state in case of sudden system or application death. It can also be used to preload values into the cache. The latter are GOB save files generated when the cache is properly closed and are the rpeferred mode to load the cache at application (re)start.

jac has been compiled and tested for the following pairs:

• linux/arm
• linux/arm64
• linux/amd64
• openWRT/mipsle
• windows/amd64

jac is built to accept data of any type, however the data will be always stored as a string and, to be type agnostic, will be also returned as a string.

Installation

go get github.com/fpessolano/jac

Usage

package main

import (
	"fmt"
	"github.com/fpessolano/jac"
	"os"
)

func main() {
    // Initialise the cache. The options below are the standard values
    if err := jac.Initialise(true, nil); err != jac.IllegalParameter && err != nil {
        fmt.Println(err)
        os.Exit(0)
    }
	
    // Create a cache bucket called test with a default expiration time (see types.go)
    test, err := jac.NewBucket("definitions", jac.NoExpiration)
    if err != nil {
        fmt.Println(err)
        os.Exit(0)
    }

    // Set a persistent value of the key "one" to "1", with the default expiration time
    test.Set("one", 1, jac.DefaultExpiration, true)
    
    // Set a non-persistent value of the key "b" to "2", with no expiration time
    test.Set("two", "two", jac.NoExpiration, false)
    
    // Get the value associated with the key "one" from the cache
    oneRead, found := test.Get("two")
    if found {
        fmt.Println(oneRead)
    }
	
    // Get all items in bucket test
    allItems := test.Items()
    for _, el := range(allItems) {
        fmt.Println(el)	
    }
    
    // Close the bucket
    test.Close(false)
    
    // Close the cache
    jac.Terminate()
}

Available methods

    // Initialise prepare the cache for use. It accept two parameters:
    //  v : set to true for verbose (useful for development purposes)
    //  o : are the database options (see inm types.go for further details)
    func Initialise(v bool, o *Options) error
    
    // Terminate closes the cache and relative processes
    func Terminate()
    
    // NewBucket create a new bucket in the cache.
    //  If a rec file or a data file are present and are not older than time.Now() - maxage,
    //  they will be loaded in the cache
    func NewBucket(name string, exp time.Duration) (c Bucket, e error) 
    
    // Close closes a bucket storing values in the recovery data
    //  if keep is false the working data file will be deleted
    func (c *Bucket) Close(keep bool) 
    
    // Get read the value associated to the key k/
    //  It also returns false if the key has not value associated to it
    func (c *Bucket) Get(k string) (string, bool) 
    
    // GetWithExpiration performs the same operation as Get but it also returns the
    //  value expiration time
    func (c *Bucket) GetWithExpiration(k string) (string, time.Time, bool) 
    
    // Set writes a new key/value pair with a given expiration time t and
    //  It marks the key/value pair persistent if pers is true.
    func (c *Bucket) Set(k string, vn interface{}, t time.Duration, pers bool) 
    
    // Update updates the key/value pair with a given expiration time t and
    //  It marks the key/value pair persistent if pers is true. The working file is not changed
    //  even if pers is true
    func (c *Bucket) Update(k string, vn interface{}, t time.Duration, pers bool) 
    
    // Replace replaces an existing key/value pair only it already existing.
    //  It marks the key/value pair persistent if pers is true.
    func (c *Bucket) Replace(k string, vn interface{}, t time.Duration, pers bool) 
    
    // Add add a new key/value pair only if it does not already
    //  It marks the key/value pair persistent if pers is true.
    func (c *Bucket) Add(k string, vn interface{}, t time.Duration, pers bool) (string, bool) 
    
    // FunctionUpdate updates the new key/value with a custom function of type
    //  func(k, v string) (string, string). The function is given the actual key/value pair is present
    //  and key/"" otherwise and it expects a new key/value pair.
    //  if the function modofies the key, the old key/pair is deleted.
    //  It marks the key/value pair persistent if pers is true.
    func (c *Bucket) FunctionUpdate(k string, f updateFunc, t time.Duration, pers bool) (string, string, bool) 
    
    // Items returns all elements in the bucket as a map[string]string
    func (c *Bucket) Items() (rt map[string]string) 
    
    // Delete permanently removes an item from the bucket
    func (c *Bucket) Delete(k string) 
    
    // Compact initiate a compation request of the working files.
    //  Please note that all values will be used and any previously indicated persistence flag will be ignored.
    func (c *Bucket) Compact() 
    
    // Flush deletes all items from the bucket.
    func (c *Bucket) Flush() 
    
    // ItemCount returns the number of items in the bucket. This may include items that have
    //  expired, but have not yet been cleaned up.
    func (c *Bucket) ItemCount() int 
    
    // OnEvicted sets an (optional) function that is called with the key and value when an
    //  item is evicted from the bucketInternal. (Including when it is deleted manually, but
    //  not when it is overwritten.) Set to nil to disable.
    func (c *Bucket) OnEvicted(f func(string, interface{})) 
    
    // DeleteExpired deletes all expired items from the bucketInternal.
    func (c *Bucket) DeleteExpired() 

Documentation

Index

• Constants
• Variables
• func Initialise(v bool, o *Options) error
• func Terminate()
• type Bucket
  • func NewBucket(name string, exp time.Duration) (c Bucket, e error)
  • func (c *Bucket) Add(k string, vn interface{}, t time.Duration, pers bool) (string, bool)
  • func (c *Bucket) Close(keep bool)
  • func (c *Bucket) Compact()
  • func (c *Bucket) Delete(k string)
  • func (c *Bucket) DeleteExpired()
  • func (c *Bucket) Flush()
  • func (c *Bucket) FunctionUpdate(k string, f updateFunc, t time.Duration, pers bool) (string, string, bool)
  • func (c *Bucket) Get(k string) (string, bool)
  • func (c *Bucket) GetWithExpiration(k string) (string, time.Time, bool)
  • func (c *Bucket) ItemCount() int
  • func (c *Bucket) Items() (rt map[string]string)
  • func (c *Bucket) OnEvicted(f func(string, interface{}))
  • func (c *Bucket) Replace(k string, vn interface{}, t time.Duration, pers bool)
  • func (c *Bucket) Set(k string, vn interface{}, t time.Duration, pers bool)
  • func (c *Bucket) Update(k string, vn interface{}, t time.Duration, pers bool)
• type FileData
• type Item
• type Options

Constants

const (
	// To be used to set key/pair without expiration date
	NoExpiration time.Duration = -1
	// To be used to set key/pair with expiration date as from the bucket declaration
	DefaultExpiration time.Duration = 0
)

Variables

var (
	IllegalParameter = errors.New("illegal parameter given")
)

Functions

func Initialise

func Initialise(v bool, o *Options) error

Initialise prepare the cache for use. It accept two parameters:

v : set to true for verbose (useful for development purposes)
o : are the database options (see inm types.go for further details)

func Terminate

func Terminate()

Terminate closes the cache and relative processes

Types

type Bucket

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

func NewBucket

func NewBucket(name string, exp time.Duration) (c Bucket, e error)

NewBucket create a new bucket in the cache.

If a rec file or a data file are present and are not older than time.Now() - maxage,
they will be loaded in the cache

func (*Bucket) Add

func (c *Bucket) Add(k string, vn interface{}, t time.Duration, pers bool) (string, bool)

Add add a new key/value pair only if it does not already

It marks the key/value pair persistent if pers is true.

func (*Bucket) Close

func (c *Bucket) Close(keep bool)

Close closes a bucket storing values in the recovery data

if keep is false the working data file will be deleted

func (*Bucket) Compact

func (c *Bucket) Compact()

Compact initiate a compation request of the working files.

Please note that all values will be used and any previously indicated persistence flag will be ignored.

func (*Bucket) Delete

func (c *Bucket) Delete(k string)

Delete permanently removes an item from the bucket

func (*Bucket) DeleteExpired

func (c *Bucket) DeleteExpired()

DeleteExpired deletes all expired items from the bucketInternal.

func (*Bucket) Flush

func (c *Bucket) Flush()

Flush deletes all items from the bucket.

func (*Bucket) FunctionUpdate

func (c *Bucket) FunctionUpdate(k string, f updateFunc, t time.Duration, pers bool) (string, string, bool)

FunctionUpdate updates the new key/value with a custom function of type

func(k, v string) (string, string). The function is given the actual key/value pair is present
and key/"" otherwise and it expects a new key/value pair.
if the function modofies the key, the old key/pair is deleted.
It marks the key/value pair persistent if pers is true.

func (*Bucket) Get

func (c *Bucket) Get(k string) (string, bool)

Get read the value associated to the key k

It also returns false if the key has not value associated to it

func (*Bucket) GetWithExpiration

func (c *Bucket) GetWithExpiration(k string) (string, time.Time, bool)

GetWithExpiration performs the same operation as Get but it also returns the

value expiration time

func (*Bucket) ItemCount

func (c *Bucket) ItemCount() int

ItemCount returns the number of items in the bucket. This may include items that have

expired, but have not yet been cleaned up.

func (*Bucket) Items

func (c *Bucket) Items() (rt map[string]string)

Items returns all elements in the bucket as a map[string]string

func (*Bucket) OnEvicted

func (c *Bucket) OnEvicted(f func(string, interface{}))

OnEvicted sets an (optional) function that is called with the key and value when an

item is evicted from the bucketInternal. (Including when it is deleted manually, but
not when it is overwritten.) Set to nil to disable.

func (*Bucket) Replace

func (c *Bucket) Replace(k string, vn interface{}, t time.Duration, pers bool)

Replace replaces an existing key/value pair only it already existing.

It marks the key/value pair persistent if pers is true.

func (*Bucket) Set

func (c *Bucket) Set(k string, vn interface{}, t time.Duration, pers bool)

Set writes a new key/value pair with a given expiration time t and

It marks the key/value pair persistent if pers is true.

func (*Bucket) Update

func (c *Bucket) Update(k string, vn interface{}, t time.Duration, pers bool)

Update updates the key/value pair with a given expiration time t and

It marks the key/value pair persistent if pers is true. The working file is not changed
even if pers is true

type FileData

type FileData struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

type Item

type Item struct {
	Object     interface{}
	Expiration int64
}

type Options

type Options struct {
	ExpirationTime     int    // Expiration time is seconds
	IntervalCompacting int    // Cache working files compacting interval in seconds (values smaller than 60s will be defaulted to 60s)
	InternalBuffering  int    // Buffering length to decouple the in-memory cache from the disk processes. Bigger numbers improve cache speed at expenses of system crash resistance
	LoadDelayMs        int    // Regulates the start-up delay. Smaller numbers improves start-up time at costs of possible loss of persistence
	MaximumAge         int64  // Maximum age (in s) of a back-up file (.rec) or working file (.data) for it to be used to initialise the cache
	WorkingFolder      string // folder for working files (.data). File contain the entire cache in a readable. Altering the files only affects the initial cache load not its operation
	RecoveryFolder     string // folder for back-up files (.rec)
}

Default options are

ExpirationTime:     0,
IntervalCompacting: 1440 * 60,
InternalBuffering:  10,
LoadDelayMs:        10,
MaximumAge:         5 * 60,