increma

README

increma

In-memory counter cache for Go. Stores int8 counters keyed by byte slices with automatic LRU eviction.

A stripped-down, purpose-built alternative to freecache optimized for increment-only workloads.

Install

go get github.com/alexey-s-aksenov/increma

Usage

package main

import (
	"fmt"
	"github.com/alexey-s-aksenov/increma"
)

func main() {
	cache := increma.NewCache(1024 * 1024) // 1MB

	val, _ := cache.Inc([]byte("page-views"))
	fmt.Println(val) // 1

	val, _ = cache.Inc([]byte("page-views"))
	fmt.Println(val) // 2

	val, _ = cache.IncBy([]byte("page-views"), 5)
	fmt.Println(val) // 7

	val, _ = cache.IncBy([]byte("page-views"), -3)
	fmt.Println(val) // 4

	val, _ = cache.IncMax([]byte("rate-limit"), 5)
	fmt.Println(val) // 1 (или 5 если достигнут лимит, при этом в памяти — 0)
}

Comparison with freecache

	freecache	increma
API	Set/Get/Del/SetEx	Inc/IncBy/IncMax
Value type	[]byte	int8
Update strategy	Append new entry (old skipped)	In-place mutation of existing entry

Why in-place updates matter: incrementing the same key N times in freecache costs N * (16 + keyLen) bytes of ring buffer space. In increma it costs only 16 bytes total — the key is written once, and subsequent increments mutate the 16-byte header at the same offset.

Documentation

Index

• Constants
• Variables
• type Cache
  • func NewCache(size int) *Cache
  • func NewCacheCustomTimer(size int, timer Timer) *Cache
  • func (c *Cache) Inc(key []byte) int8
  • func (c *Cache) IncBy(key []byte, value int8) int8
  • func (c *Cache) IncMax(key []byte, maxValue int8) int8
• type RingBuf
  • func NewRingBuf(size int, begin int64) (rb RingBuf)
  • func (rb *RingBuf) Begin() int64
  • func (rb *RingBuf) End() int64
  • func (rb *RingBuf) EqualAt(p []byte, off int64) bool
  • func (rb *RingBuf) Evacuate(off int64, length int) (newOff int64)
  • func (rb *RingBuf) ReadAt(p []byte, off int64) (n int, err error)
  • func (rb *RingBuf) Size() int64
  • func (rb *RingBuf) Skip(length int64)
  • func (rb *RingBuf) Write(p []byte) (n int, err error)
  • func (rb *RingBuf) WriteAt(p []byte, off int64) (n int, err error)
• type StoppableTimer
  • func NewCachedTimer() StoppableTimer
• type Timer

Constants

const ENTRY_HDR_SIZE = 16

const HASH_ENTRY_SIZE = 16

Variables

var ErrOutOfRange = errors.New("out of range")

Types

type Cache

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

func NewCache

func NewCache(size int) *Cache

NewCache returns a newly initialized cache by size. The cache size will be set to 512KB at minimum.

func NewCacheCustomTimer

func NewCacheCustomTimer(size int, timer Timer) *Cache

NewCacheCustomTimer returns new cache with custom timer.

func (*Cache) Inc

func (c *Cache) Inc(key []byte) int8

func (*Cache) IncBy

func (c *Cache) IncBy(key []byte, value int8) int8

func (*Cache) IncMax

func (c *Cache) IncMax(key []byte, maxValue int8) int8

type RingBuf

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

func NewRingBuf

func NewRingBuf(size int, begin int64) (rb RingBuf)

func (*RingBuf) Begin

func (rb *RingBuf) Begin() int64

func (*RingBuf) End

func (rb *RingBuf) End() int64

func (*RingBuf) EqualAt

func (rb *RingBuf) EqualAt(p []byte, off int64) bool

func (*RingBuf) Evacuate

func (rb *RingBuf) Evacuate(off int64, length int) (newOff int64)

func (*RingBuf) ReadAt

func (rb *RingBuf) ReadAt(p []byte, off int64) (n int, err error)

func (*RingBuf) Size

func (rb *RingBuf) Size() int64

func (*RingBuf) Skip

func (rb *RingBuf) Skip(length int64)

func (*RingBuf) Write

func (rb *RingBuf) Write(p []byte) (n int, err error)

func (*RingBuf) WriteAt

func (rb *RingBuf) WriteAt(p []byte, off int64) (n int, err error)

type StoppableTimer

type StoppableTimer interface {
	Timer

	// Release resources of the timer, functionality may or may not be affected
	// It is not called automatically, so user must call it just once
	Stop()
}

Timer that must be stopped.

func NewCachedTimer

func NewCachedTimer() StoppableTimer

Create cached timer and start runtime timer that updates time every second

type Timer

type Timer interface {
	// Give current time (in seconds)
	Now() uint32
}

Timer holds representation of current time.