ttlcache

README

ttlcache

About

ttlcache – is a simple and efficient in-memory key value storage with TTL for each record.

The key is of uint64 type. Library provides wrappers for common types:

• IntKey
• ByteKey
• Int8Key
• Uint8Key
• Int16Key
• Uint16Key
• Int32Key
• Uint32Key
• Int64Key
• Uint64Key
• BytesKey ([]byte)
• StringKey
• AnyKey (interface{})

AnyKey is not suitable for very intensive usage. Consider writing your own hash function if your keys are complex types, and you faced performance degradation.

Installation

go get -u github.com/cheshir/ttlcache

Usage

package main

import (
    "github.com/cheshir/ttlcache"
)

const (
    minute = 60 * time.Second
    hour = 60 * minute
)

func main() {
    // How often we need to stop the world and remove outdated records.
	resolution := minute

	cache := ttlcache.New(resolution)
	cache.Set(ttlcache.StringKey("some key"), "value", hour)
	value, ok := cache.Get(ttlcache.StringKey("some key"))
	if !ok {
		// there is no record with key "some key" in the cache. Probably it has been expired.
	}

	fmt.Println(value.(string)) // This is necessary type assertion, because returned value is of interface{} type.
}

Performance

If you're interested in benchmarks you can check them in repository. Just play with numbers and types and check that library is suitable for your purposes.

go test -bench=. -benchmem

For those of us who wants to get some numbers without downloading unknown stuff (MacBook Pro 16"):

BenchmarkCache_Set-16            8755802               122 ns/op               8 B/op          0 allocs/op
BenchmarkCache_Get-16           57474564               19.6 ns/op              0 B/op          0 allocs/op

Documentation

Index

• func AnyKey(k interface{}) uint64
• func ByteKey(k byte) uint64
• func BytesKey(k []byte) uint64
• func Int16Key(k int16) uint64
• func Int32Key(k int32) uint64
• func Int64Key(k int64) uint64
• func Int8Key(k int8) uint64
• func IntKey(k int) uint64
• func StringKey(k string) uint64
• func Uint16Key(k uint16) uint64
• func Uint32Key(k uint32) uint64
• func Uint64Key(k uint64) uint64
• func Uint8Key(k uint8) uint64
• type Cache
  • func New(resolution time.Duration) *Cache
  • func (c *Cache) Close() error
  • func (c *Cache) Delete(key uint64)
  • func (c *Cache) Get(key uint64) (interface{}, bool)
  • func (c *Cache) Set(key uint64, value interface{}, ttl time.Duration)

Functions

func AnyKey

func AnyKey(k interface{}) uint64

AnyKey creates key from anything. Should not be used for large datasets. For complex keys you can write your own hashing implementation.

func ByteKey

func ByteKey(k byte) uint64

ByteKey creates key from byte value.

func BytesKey

func BytesKey(k []byte) uint64

BytesKey creates key from slice of bytes value.

func Int16Key

func Int16Key(k int16) uint64

Int16Key creates key from int16 value.

func Int32Key

func Int32Key(k int32) uint64

Int32Key creates key from int32 value.

func Int64Key

func Int64Key(k int64) uint64

Int64Key creates key from int64 value.

func Int8Key

func Int8Key(k int8) uint64

Int8Key creates key from int8 value.

func IntKey

func IntKey(k int) uint64

IntKey creates key from int value.

func StringKey

func StringKey(k string) uint64

StringKey creates key from string value.

func Uint16Key

func Uint16Key(k uint16) uint64

Uint16Key creates key from uint16 value.

func Uint32Key

func Uint32Key(k uint32) uint64

Uint32Key creates key from uint32 value.

func Uint64Key

func Uint64Key(k uint64) uint64

Uint64Key creates key from uint64 value.

func Uint8Key

func Uint8Key(k uint8) uint64

Uint8Key creates key from uint8 value.

Types

type Cache

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

Cache represents key-value storage.

func New

func New(resolution time.Duration) *Cache

New creates key-value storage. resolution – configures cleanup manager. Cleanup operation locks storage so think twice before setting it to small value.

func (*Cache) Close

func (c *Cache) Close() error

Close stops cleanup manager and removes records from storage.

func (*Cache) Delete

func (c *Cache) Delete(key uint64)

Delete removes record from storage.

func (*Cache) Get

func (c *Cache) Get(key uint64) (interface{}, bool)

Get returns stored record. The first returned variable is a stored value. The second one is an existence flag like in the map.

func (*Cache) Set

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

Set adds value to the cache with given ttl. ttl value should be a multiple of the resolution time value.