tearc

Documentation

Overview

Package tearc provides a KeyPool implementation that acts as an intermediate caching layer, by wrapping another underlying KeyPool that actually derives the keys. This reduces calls to the root KeyPool and therefore improves performance for hot-path (often-used) keys drastically. The underlying cache data structure is a (azoo.dev/utils/tearc).Cache (tearc standing for Timed-Eviction-Adaptive-Replacement-Cache), which tries to remove unused keys from memory as soon as possible.

The caching data structure itself is moved into a standalone utils module, so it can be used and imported by other projects easily.

Index

• type Config
• type KeyPool
  • func New(config *Config, pool KeyPool, log logger.Logger) (KeyPool, error)

Types

type Config

type Config struct {
	// Size is the size of the underlying tearc Cache. For example: 65536
	Size int
	// Shards is the amount of shards used in the underlying tearc Cache. For
	// example: 64
	Shards int
	// BucketMinTick is the minimum amount of time between bucket reaper runs.
	// For example: 1 * time.Second
	BucketMinTick time.Duration
	// BucketMaxTick is the maximum amount of time between bucket reaper runs.
	// For example: 10 * time.Second
	BucketMaxTick time.Duration
	// AliveTime specifies how long cached keys should stay alive (in RAM) at
	// maximum. They may get replaced sooner by page replacement (ARC). For
	// example: 1 * time.Minute
	AliveTime time.Duration
}

Config provides all options for a tearc KeyPool. Every field is required. Not providing valid configuration values results in unspecified behaviour. No checks are carried out!

type KeyPool

type KeyPool interface {
	// KDF32 is a key derivation function that returns a 32-byte key for the
	// keyRing passed to it. Equal keyRings must always result in equal keys.
	KDF32(keyRing []byte) (key []byte, err error)
	// KDF64 is a key derivation function that returns a 64-byte key for the
	// keyRing passed to it. Equal keyRings must always result in equal keys.
	KDF64(keyRing []byte) (key []byte, err error)
	// Close closes the KeyPool and it's underlying instances.
	Close() error
}

KeyPool is an interface for a key derivation loader. It is copied from the parent project azoo.dev/utils/dvx

func New

func New(config *Config, pool KeyPool, log logger.Logger) (KeyPool, error)

New creates a new tearc Cache and wraps it as a KeyPool instance with the underlying KeyPool `pool` as actual loader.