buffercache

Documentation

Overview

Package buffercache provides the BufferCache type, a kind of map[string][]byte that is optimized for appending new bytes to the cache values. BufferCache has a maximum capacity and flushes itself when it's reached and calling a user- provided callback with the flushed buffers.

BufferCache also supports compressing the byte buffers it holds with lz4 in order to trade cpu for memory, buffers are transparently uncompressed when the flush callback is called.

Index

• type BufferCache
  • func New(cfg Config) (*BufferCache, error)
  • func (c *BufferCache) Flush()
  • func (c *BufferCache) Metrics() Metrics
  • func (c *BufferCache) Put(key string, buf []byte)
• type Config
• type Metrics

Types

type BufferCache

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

A BufferCache is like a map[string][]byte that is optimized for appending new bytes to the cache values.

func New

func New(cfg Config) (*BufferCache, error)

New creates a new BufferCache.

A BufferCache is made of 2 components, a cold cache for keys that have been presented to the cache only once, and a hot cache for the keys having been seen more than once. In other words, when putting a (key, buffer) pair into the cache, the buffer is either copied into the cold cache if the key is not present already, or, in case a buffer already exists within the cache for that key, the new buffer gets appended to the previous one, separated by '\n'.

The cold cache is flushed when it's full.

The hot cache is flushed on the following occasions: - upon appending a buffer, the total buffer for that key would exceed maxBufferLength; in that case the previous buffer is passed to flush. - upon the insertion of new (key, buffer) pair, the total capacity of the cache would exceed maxCapacity; in that case the whole cache is empty (i.e buffers of all keys are passed to flush).

func (*BufferCache) Flush

func (c *BufferCache) Flush()

Flush flushes the whole cache.

func (*BufferCache) Metrics

func (c *BufferCache) Metrics() Metrics

Metrics returns a snapshot of the cache performance counters.

This is not safe for concurrent use by multiple goroutines.

func (*BufferCache) Put

func (c *BufferCache) Put(key string, buf []byte)

Put puts buf in the cache.

Either a new index, key, is created with buf, or buf is appended to the previous buffer that is indexed by key.

This may trigger flush(es).

type Config

type Config struct {

	// MaxCapacity is the maximum size in bytes the BufferCache can hold
	// without in dynamic memory (hot cache). This does not take into account
	// the buckets memory.
	MaxCapacity int

	// MaxBufferLength is the maximum size the buffer of a single key can reach
	// without being flushed.
	MaxBufferLength int

	// CellsPerBucket is the number of cells (or buffers) a bucket can contain.
	// It is expected that a majority of keys are going to hold a single buffer,
	// so each of those buffers can directly copied in pre-allocated memory
	// regions, called cells, which are limited in size. A bucket group cells
	// of the same size together.
	//
	// NOTE: this number must be a multiple of 64 or the configuration is invalid.
	CellsPerBucket int

	// Buckets indicates the cell sizes in bytes, for the various buckets.
	Buckets []int

	// OnFlush is the function called to flush the cache content when more
	// memory is required. It is called once per key with the whole buffer for
	// that key.
	OnFlush func([]byte)

	// EnableCompression indicates whether buffers should be compressed in memory
	// with a fast compression algorithm. This option is transparent, meaning
	// buffers are uncompressed in their original form when flushed. Hence
	// enabling this option trades CPU for memory.
	EnableCompression bool
}

Config configures a BufferCache.

type Metrics

type Metrics struct {
	Cold         coldCacheMetrics
	Hot          hotCacheMetrics
	TotalFlushes uint64 // flushes since cache creation
}

Metrics holds a snapshot of the performance counters of a BufferCache instance.