cachekit

README

Cachekit

Cachekit is a lightweight, thread-safe, in-memory key/value store and caching solution for Go applications. It provides a simple and efficient way to store and retrieve objects with optional expiration times. The package now includes a sharded cache system for improved performance and scalability.

Features

• Thread-safe operations for concurrent access
• Flexible expiration times for cached items
• Support for storing any Go object (interface{})
• Optional default expiration time for the entire cache
• Easy-to-use API for adding, retrieving, and removing cache entries
• Sharded cache system for better performance with high concurrency

Use Cases

Cachekit is ideal for:

• Temporary data storage in web applications
• Caching expensive database queries or API calls
• Implementing rate limiting or throttling mechanisms
• Storing session data
• Any scenario requiring fast, in-memory data access with automatic expiration
• High-concurrency environments where a sharded cache can improve performance

Basic Usage

import (
    "github.com/1dylan1/cachekit"
    "time"
)

// Create a new cache with a default expiration time of 5 minutes for an entry, and a routine cleanup time of 10 minutes
cache := cachekit.New(5 * time.Minute, 10 * time.Minute)

// Add an item to the cache with the default expiration time we initially set
cache.Add("key", "value", cache.DefaultExpirationTime)

//Update existing value or add new value
cache.Set("key", "value",  cache.NoExpirationTime)

// Retrieve an item from the cache
value, found := cache.Get("key")
if found {
    // Use the value
}

// Remove an item from the cache
cache.Delete("key")

// 'Flush' the cache, removing all entries from it, becoming empty
cache.Flush()

Sharded Cache Usage

The sharded cache system provides better performance for high-concurrency scenarios by distributing cache entries across multiple shards. The sharded cache provides the same API as the regular, non-sharded single cache.

import (
    "github.com/1dylan1/cachekit"
    "time"
)

// Create a new sharded cache with 16 shards, default expiration time of 5 minutes, and cleanup time of 10 minutes
shardedCache := cachekit.NewShardedCache(16, 5*time.Minute, 10*time.Minute)

// Add an item to the sharded cache
shardedCache.Add("key", "value", 5*time.Minute)

// Retrieve an item from the sharded cache
value, found := shardedCache.Get("key")
if found {
    // Use the value
}

// Remove an item from the sharded cache
shardedCache.Delete("key")

// Flush all shards in the cache
shardedCache.Flush()

Documentation

Index

• Constants
• type Cache
  • func New(expirationTime time.Duration, cleanupTime time.Duration) *Cache
  • func (Cache *Cache) Add(key string, content interface{}, expirationTime time.Duration) error
  • func (Cache *Cache) Delete(key string) error
  • func (Cache *Cache) Flush()
  • func (Cache *Cache) Get(key string) (interface{}, bool)
  • func (Cache *Cache) GetWithExpiration(key string) (interface{}, time.Time, bool)
  • func (Cache *Cache) Length() int
  • func (Cache *Cache) Set(key string, content interface{}, expirationTime time.Duration)
• type ShardedCache
  • func NewShardedCache(shardCount int, expirationTime time.Duration, cleanupTime time.Duration) *ShardedCache
  • func (shardedCache *ShardedCache) Add(key string, content interface{}, expirationTime time.Duration) error
  • func (shardedCache *ShardedCache) Delete(key string) error
  • func (shardedCache *ShardedCache) Flush()
  • func (shardedCache *ShardedCache) Get(key string) (interface{}, bool)
  • func (shardedCache *ShardedCache) GetWithExpiration(key string) (interface{}, time.Time, bool)
  • func (shardedCache *ShardedCache) Set(key string, content interface{}, expirationTime time.Duration)

Constants

const (
	DefaultExpirationTime time.Duration = 0
	NoExpirationTime      time.Duration = -1
)

Types

type Cache

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

func New

func New(expirationTime time.Duration, cleanupTime time.Duration) *Cache

func (*Cache) Add

func (Cache *Cache) Add(key string, content interface{}, expirationTime time.Duration) error

Tries to add a key/entry into the Cache. If the Cache already has that key it will throw an error. If you'd like to add (or "update") a value even if its key exists, use the Set method

func (*Cache) Delete

func (Cache *Cache) Delete(key string) error

func (*Cache) Flush

func (Cache *Cache) Flush()

Cleans the Cache of all entries

func (*Cache) Get

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

Returns the entry from the Cache from given key, and a bool if it was found or not. If the key has no object associated with it, or wasn't found, returns nil.

func (*Cache) GetWithExpiration

func (Cache *Cache) GetWithExpiration(key string) (interface{}, time.Time, bool)

Returns the entry from the Cache with given key, the time of the expiration, and bool if it was found or not. If the key has no object associated with it, or wasn't found, returns nil.

func (*Cache) Length

func (Cache *Cache) Length() int

Returns the number of entries in the Cache.

func (*Cache) Set

func (Cache *Cache) Set(key string, content interface{}, expirationTime time.Duration)

Adds or updates a key/entry to the Cache, ignoring if the key already exists or not.

type ShardedCache

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

func NewShardedCache

func NewShardedCache(shardCount int, expirationTime time.Duration, cleanupTime time.Duration) *ShardedCache

func (*ShardedCache) Add

func (shardedCache *ShardedCache) Add(key string, content interface{}, expirationTime time.Duration) error

func (*ShardedCache) Delete

func (shardedCache *ShardedCache) Delete(key string) error

func (*ShardedCache) Flush

func (shardedCache *ShardedCache) Flush()

func (*ShardedCache) Get

func (shardedCache *ShardedCache) Get(key string) (interface{}, bool)

func (*ShardedCache) GetWithExpiration

func (shardedCache *ShardedCache) GetWithExpiration(key string) (interface{}, time.Time, bool)

func (*ShardedCache) Set

func (shardedCache *ShardedCache) Set(key string, content interface{}, expirationTime time.Duration)