go-cache — In-Memory Key-Value Cache for Go Applications

Introduction

go-cache is an in-memory key-value cache library for Go that stores arbitrary data with optional expiration times. It is designed for single-process applications that need a fast, thread-safe caching layer without the operational overhead of an external cache server. Items expire automatically and are cleaned up by a background goroutine.

What go-cache Does

• Stores any Go value by string key with configurable per-item expiration
• Provides thread-safe concurrent access using sync.RWMutex
• Runs a background janitor goroutine that removes expired items at a configurable interval
• Supports atomic increment and decrement operations on numeric values
• Allows serialization of cache contents to and from files for persistence across restarts

Architecture Overview

go-cache wraps a map[string]Item behind a sync.RWMutex for concurrent safety. Each Item holds the value as an interface{} and an expiration timestamp. A separate janitor goroutine periodically scans the map and deletes expired entries. The library keeps the design intentionally simple: no sharding, no eviction policies, and no distributed features, prioritizing ease of use for single-node scenarios.

Self-Hosting & Configuration

• Import the package and create a cache with New(defaultExpiration, cleanupInterval)
• Set items with per-key expiration or use cache.DefaultExpiration for the cache-wide default
• Use cache.NoExpiration for items that should never expire automatically
• Call SaveFile/LoadFile to persist cache state to disk and restore on startup
• Set an OnEvicted callback to run custom logic when items are removed

Key Features

• Zero dependencies: pure Go with no external packages required
• Thread-safe: concurrent reads and writes are safe out of the box
• Flexible expiration: per-item TTLs, default TTL, or no expiration
• Atomic counters: Increment and Decrement operations for rate limiting and metrics
• Persistence: save and load cache contents to files for crash recovery

Comparison with Similar Tools

• Ristretto — more sophisticated cache with admission and eviction policies (TinyLFU); better for high-throughput scenarios where hit ratio optimization matters
• BigCache — designed for large datasets with reduced GC pressure via byte-level storage; go-cache is simpler for general-purpose use
• FreeCache — zero-GC cache using pre-allocated memory; trades flexibility for GC performance
• Redis — external cache server with persistence, replication, and data structures; go-cache avoids network overhead for single-process needs

FAQ

Q: Is go-cache suitable for production use? A: Yes, for single-process applications. It is widely used in production for API response caching, session storage, and rate limiting within a single Go service.

Q: How does it handle memory limits? A: go-cache does not enforce memory limits or eviction policies. If you need bounded memory, consider Ristretto or BigCache which support size-based eviction.

Q: Is the cache shared across multiple Go processes? A: No. go-cache is in-process only. For shared caching across services, use Redis, Memcached, or a distributed cache.

Q: Can I iterate over all items? A: Yes. Use the Items() method to get a copy of all unexpired items as a map, or use the cache's internal map with appropriate locking.

Sources

• https://github.com/patrickmn/go-cache
• https://pkg.go.dev/github.com/patrickmn/go-cache