How does FreeLRU compare to Ristretto for Go caching?

FreeLRU focuses on GC-less design and raw speed, often outperforming Ristretto in benchmarks, but Ristretto offers more features like cost-based eviction. FreeLRU's ShardedLRU is better for high-throughput scenarios, while Ristretto handles concurrency differently with separate goroutines.

What hash function should I use with FreeLRU for best performance?

For integer keys, AESENC hash is fastest on supported CPUs, while for strings, XXH3 is recommended. The README provides benchmarks comparing hash functions, and you can find examples in the bench/ directory to guide your choice.

How to choose between SyncedLRU and ShardedLRU?

Use SyncedLRU for low-concurrency environments where lock contention isn't an issue, and ShardedLRU for high-concurrency applications. Benchmarks show ShardedLRU is up to 37x faster than SyncedLRU under high load, but it uses approximate LRU eviction.

Does FreeLRU support cache expiration with TTL?

No, FreeLRU does not have built-in TTL support; it relies purely on LRU eviction. You would need to implement time-based expiration manually, which adds complexity compared to libraries with native TTL features.

How to implement a custom hash function for FreeLRU?

You need to define a function that takes the key type and returns a uint32 hash. The README includes examples like hashStringXXHASH using xxhash, and you can refer to the bench/ directory for more implementations, including optimized versions for specific types.

Is FreeLRU thread-safe by default?

No, the base LRU is single-threaded. For thread-safety, you must explicitly use SyncedLRU or ShardedLRU, or implement your own locking. This adds an extra step compared to some caching libraries that are thread-safe out of the box.

go-freelru — GC-Less Generic LRU Hashmap Library

What is go-freelru?

FreeLRU is a Go library that implements a high-performance, GC-less LRU (Least Recently Used) hashmap for caching. It solves the problem of garbage collection overhead in long-running applications with large caches by using a contiguous memory layout and Go generics for type safety. The library provides single-threaded and thread-safe variants optimized for different concurrency levels.

Target Audience

Go developers building performance-sensitive applications that require efficient in-memory caching, such as web servers, data processing pipelines, or real-time systems where low latency and minimal GC pauses are critical.

Value Proposition

Developers choose FreeLRU for its exceptional speed, zero-allocation design for non-pointer types, and flexibility in concurrency models. It outperforms many popular Go caching libraries in benchmarks while offering a simple API and configurable memory overcommitment to tune performance.

Overview

FreeLRU is a high-performance LRU (Least Recently Used) caching library for Go designed to eliminate garbage collection overhead and provide type safety through generics. It offers multiple implementations tailored for different concurrency needs, from single-threaded to high-concurrency environments.

Key Features

GC-less Design — Uses a contiguous array to avoid millions of small heap allocations, reducing garbage collection pauses.
Generic Type Safety — Leverages Go generics for compile-time type checking and zero runtime allocations for non-pointer types.
Multiple Concurrency Models — Provides LRU (single-threaded), SyncedLRU (low-concurrency), and ShardedLRU (high-concurrency) implementations.
High Performance — Benchmarks show it outperforms other LRU libraries and even Go maps in many scenarios.
Configurable Memory Overcommitment — Allows allocating more hashtable memory to reduce collisions and improve speed.
Exact and Approximate LRU — LRU and SyncedLRU use exact LRU algorithms; ShardedLRU uses an approximate algorithm for scalability.

Philosophy

FreeLRU prioritizes performance and low GC overhead by merging hashmap and ringbuffer into a contiguous array, ensuring memory locality and minimizing cache misses. It emphasizes simplicity in API design to ease migration from other LRU implementations.

Use Cases

Best For

Reducing garbage collection overhead in long-running Go services
High-concurrency applications needing scalable LRU caching
Caching primitive types (int, string) without heap allocations
Migrating from other LRU libraries with minimal API changes
Performance-critical systems where cache speed impacts latency
Implementing custom caches with exact or approximate LRU eviction

Not Ideal For

Applications requiring automatic time-based expiration (TTL) for cache entries
Projects that need eviction callbacks or hooks for cache management
Environments where providing custom hash functions adds unnecessary complexity
High-concurrency scenarios relying solely on SyncedLRU without sharding

Pros & Cons

Pros

GC-Free Performance

Uses a contiguous array to eliminate heap allocations, achieving zero allocations per operation in benchmarks and reducing GC pauses for long-running applications.

Type-Safe Generics

Leverages Go generics for compile-time type checking and zero runtime allocations for non-pointer types, ensuring both safety and efficiency as highlighted in the README.

Scalable Concurrency Models

Offers SyncedLRU for low concurrency and ShardedLRU for high concurrency, with benchmarks showing ShardedLRU outperforming competitors like Ristretto in parallel tests.

Configurable Memory Overcommitment

Allows allocating extra hashtable memory to reduce collisions, improving speed by up to 20% in performance tests, as demonstrated in the benchmarks section.

Cons

Manual Hash Function Requirement

Callers must provide their own hash function for keys, adding setup overhead and potential for performance issues if suboptimal hashes are chosen, as admitted in the README.

Limited Eviction Features

Supports only LRU eviction without built-in TTL or other policies, missing common caching features that might be needed for applications with complex expiration logic.

Lock Contention in SyncedLRU

The SyncedLRU implementation suffers from significant lock contention in high-concurrency environments, as benchmarks show it performs poorly compared to sharded alternatives.

What is go-freelru?

Target Audience

Value Proposition

Overview

Key Features

GC-less Design — Uses a contiguous array to avoid millions of small heap allocations, reducing garbage collection pauses.
Generic Type Safety — Leverages Go generics for compile-time type checking and zero runtime allocations for non-pointer types.
Multiple Concurrency Models — Provides LRU (single-threaded), SyncedLRU (low-concurrency), and ShardedLRU (high-concurrency) implementations.
High Performance — Benchmarks show it outperforms other LRU libraries and even Go maps in many scenarios.
Configurable Memory Overcommitment — Allows allocating more hashtable memory to reduce collisions and improve speed.
Exact and Approximate LRU — LRU and SyncedLRU use exact LRU algorithms; ShardedLRU uses an approximate algorithm for scalability.

Philosophy

Use Cases

Best For

Reducing garbage collection overhead in long-running Go services
High-concurrency applications needing scalable LRU caching
Caching primitive types (int, string) without heap allocations
Migrating from other LRU libraries with minimal API changes
Performance-critical systems where cache speed impacts latency
Implementing custom caches with exact or approximate LRU eviction

Not Ideal For

Applications requiring automatic time-based expiration (TTL) for cache entries
Projects that need eviction callbacks or hooks for cache management
Environments where providing custom hash functions adds unnecessary complexity
High-concurrency scenarios relying solely on SyncedLRU without sharding

Pros & Cons

Pros

GC-Free Performance

Uses a contiguous array to eliminate heap allocations, achieving zero allocations per operation in benchmarks and reducing GC pauses for long-running applications.

Type-Safe Generics

Leverages Go generics for compile-time type checking and zero runtime allocations for non-pointer types, ensuring both safety and efficiency as highlighted in the README.

Scalable Concurrency Models

Offers SyncedLRU for low concurrency and ShardedLRU for high concurrency, with benchmarks showing ShardedLRU outperforming competitors like Ristretto in parallel tests.

Configurable Memory Overcommitment

Allows allocating extra hashtable memory to reduce collisions, improving speed by up to 20% in performance tests, as demonstrated in the benchmarks section.

Cons

Manual Hash Function Requirement

Callers must provide their own hash function for keys, adding setup overhead and potential for performance issues if suboptimal hashes are chosen, as admitted in the README.

Limited Eviction Features

Supports only LRU eviction without built-in TTL or other policies, missing common caching features that might be needed for applications with complex expiration logic.

Lock Contention in SyncedLRU

The SyncedLRU implementation suffers from significant lock contention in high-concurrency environments, as benchmarks show it performs poorly compared to sharded alternatives.

go-freelru

What is go-freelru?

Overview

Key Features

Philosophy

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

go-freelru

What is go-freelru?

Overview

Key Features

Philosophy

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?