cache

README

turbinelabs/cache

This project is no longer maintained by Turbine Labs, which has shut down.

The cache project provides a simple Cache interface, with several concrete implementations.

Requirements

• Go 1.10.3 or later (previous versions may work, but we don't build or test against them)

Dependencies

The cache project depends on our nonstdlib package; the tests depend on our test package. It should always be safe to use HEAD of all master branches of Turbine Labs open source projects together, or to vendor them with the same git tag.

A gomock-based MockCache is provided.

Additionally, we vendor github.com/hashicorp/golang-lru. This should be considered an opaque implementation detail, see Vendoring for more discussion.

Install

go get -u github.com/turbinelabs/cache/...

Clone/Test

mkdir -p $GOPATH/src/turbinelabs
git clone https://github.com/turbinelabs/cache.git > $GOPATH/src/turbinelabs/cache
go test github.com/turbinelabs/cache/...

Godoc

cache

Versioning

Please see Versioning of Turbine Labs Open Source Projects.

Pull Requests

Patches accepted! Please see Contributing to Turbine Labs Open Source Projects.

Code of Conduct

All Turbine Labs open-sourced projects are released with a Contributor Code of Conduct. By participating in our projects you agree to abide by its terms, which will be carefully enforced.

Documentation

Overview

Package cache provides a simple Cache interface, with several concrete implementations.

Index

• type Cache
  • func NewLRU(size int) (Cache, error)
  • func NewNoopCache() Cache
  • func NewTTL(size int, ttl time.Duration) (Cache, error)
• type CountingCache
  • func NewCountingCache(size int) (CountingCache, error)
  • func NewNoopCountingCache() CountingCache
• type MockCache
  • func NewMockCache(ctrl *gomock.Controller) *MockCache
  • func (m *MockCache) Add(key, value interface{}) bool
  • func (m *MockCache) Clear()
  • func (m *MockCache) EXPECT() *MockCacheMockRecorder
  • func (m *MockCache) ForEach(f func(interface{}, interface{}))
  • func (m *MockCache) Get(key interface{}) (interface{}, bool)
  • func (m *MockCache) Len() int
  • func (m *MockCache) Remove(key interface{}) bool
• type MockCacheMockRecorder
  • func (mr *MockCacheMockRecorder) Add(key, value interface{}) *gomock.Call
  • func (mr *MockCacheMockRecorder) Clear() *gomock.Call
  • func (mr *MockCacheMockRecorder) ForEach(f interface{}) *gomock.Call
  • func (mr *MockCacheMockRecorder) Get(key interface{}) *gomock.Call
  • func (mr *MockCacheMockRecorder) Len() *gomock.Call
  • func (mr *MockCacheMockRecorder) Remove(key interface{}) *gomock.Call

Types

type Cache

type Cache interface {
	// Retrieve an item from the cache. The second parameter
	// indicates whether an entry was found, allowing callers to
	// distinguish a nil value from "not found."
	Get(key interface{}) (interface{}, bool)

	// ForEach invokes f for each key/value in the cache. Callers should not depend
	// on deterministic ordering.
	ForEach(f func(key, value interface{}))

	// Add an item to the cache. Returns true if it replaced an
	// existing item. The value may be nil.
	Add(key, value interface{}) bool

	// Removes an item from the cache. Returns true if an item was
	// removed.
	Remove(key interface{}) bool

	// Remove all items from the cache.
	Clear()

	// Returns the number of items in the cache.
	Len() int
}

Cache represents a generic Cache. Specific Cache implementations may provide LRU or expiration semantics.

func NewLRU

func NewLRU(size int) (Cache, error)

NewLRU creates a new, thread-safe LRU cache with a maximum size. When adding a key would exceed the maximum size, the least recently used key is evicted to make space. Invocations of Get or Add modify eviction ordering by marking the given key as the most recently used key. Invocations of ForEach do not modify eviction ordering.

func NewNoopCache

func NewNoopCache() Cache

NewNoopCache returns a Cache implementation that caches nothing.

func NewTTL

func NewTTL(size int, ttl time.Duration) (Cache, error)

NewTTL create a new cache with a maximum size and a TTL for cache entries. When the cache is full and a new key is added, a linear search is undertaken to find an expired cache entry for eviction before evicting the least recently used cache entry. Invocations of ForEach do not modify the LRU eviction list but expired items are never returned from ForEach.

type CountingCache

type CountingCache interface {
	// Get retrieves the count for the given key.
	Get(key string) int

	// ForEach invokes f for each key/couunt in the cache. Callers should not depend
	// on deterministic ordering.
	ForEach(f func(key string, count int))

	// Inc increases the count for the given key by n, which may be negative. Return
	// its new value.
	Add(key string, n int) int

	// Inc increments the count for the given key by 1 and returns its new values.
	Inc(key string) int

	// Dec decrements the count for the given key by 1 and returns its new value.
	Dec(key string) int

	// Remove removes the key and returns its previous value.
	Remove(key string) int

	// Clear removes all keys.
	Clear()

	// Len returns the number of entries in the cache.
	Len() int
}

CountingCache represents a Cache specialized for counting strings.

func NewCountingCache

func NewCountingCache(size int) (CountingCache, error)

NewCountingCache creates a CountingCache that tracks integer counts for at most size unique string keys. When the number of keys in the cache reaches size, the next new key added will randomly replace a key among the set of keys with the smallest count, even if that count is larger than the newly added key's value. Size must be at least 2.

func NewNoopCountingCache

func NewNoopCountingCache() CountingCache

NewNoopCountingCache returns a CountingCache implementation that counts nothing.

type MockCache

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

MockCache is a mock of Cache interface

func NewMockCache

func NewMockCache(ctrl *gomock.Controller) *MockCache

NewMockCache creates a new mock instance

func (*MockCache) Add

func (m *MockCache) Add(key, value interface{}) bool

Add mocks base method

func (*MockCache) Clear

func (m *MockCache) Clear()

Clear mocks base method

func (*MockCache) EXPECT

func (m *MockCache) EXPECT() *MockCacheMockRecorder

EXPECT returns an object that allows the caller to indicate expected use

func (*MockCache) ForEach

func (m *MockCache) ForEach(f func(interface{}, interface{}))

ForEach mocks base method

func (*MockCache) Get

func (m *MockCache) Get(key interface{}) (interface{}, bool)

Get mocks base method

func (*MockCache) Len

func (m *MockCache) Len() int

Len mocks base method

func (*MockCache) Remove

func (m *MockCache) Remove(key interface{}) bool

Remove mocks base method

type MockCacheMockRecorder

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

MockCacheMockRecorder is the mock recorder for MockCache

func (*MockCacheMockRecorder) Add

func (mr *MockCacheMockRecorder) Add(key, value interface{}) *gomock.Call

Add indicates an expected call of Add

func (*MockCacheMockRecorder) Clear

func (mr *MockCacheMockRecorder) Clear() *gomock.Call

Clear indicates an expected call of Clear

func (*MockCacheMockRecorder) ForEach

func (mr *MockCacheMockRecorder) ForEach(f interface{}) *gomock.Call

ForEach indicates an expected call of ForEach

func (*MockCacheMockRecorder) Get

func (mr *MockCacheMockRecorder) Get(key interface{}) *gomock.Call

Get indicates an expected call of Get

func (*MockCacheMockRecorder) Len

func (mr *MockCacheMockRecorder) Len() *gomock.Call

Len indicates an expected call of Len

func (*MockCacheMockRecorder) Remove

func (mr *MockCacheMockRecorder) Remove(key interface{}) *gomock.Call

Remove indicates an expected call of Remove