NAME

lru - LRU cache with O(1) operations

SYNOPSIS

use lru;

# Create cache with max 1000 entries
my $cache = lru::new(1000);

# Store values - O(1)
$cache->set('key1', $value);
$cache->set('user:123', { name => 'Bob', age => 30 });

# Retrieve values - O(1), promotes to front
my $val = $cache->get('key1');

# Check existence without promoting - O(1)
if ($cache->exists('key1')) { ... }

# Peek without promoting - O(1)
my $val = $cache->peek('key1');

# Delete entry - O(1)
$cache->delete('key1');

# Cache info
my $size = $cache->size;      # Current entries
my $cap = $cache->capacity;   # Max entries

# Clear all entries
$cache->clear;

# Get all keys (most recent first)
my @keys = $cache->keys;

The function-style API you should use

use lru qw(import);

my $cache = lru::new(1000);

# Function-style ops eliminate method dispatch overhead
# ~2x faster than method calls
lru_set($cache, 'key', $value);    # 40M+ ops/sec
my $v = lru_get($cache, 'key');    # 62M+ ops/sec
lru_exists($cache, 'key');         # 60M+ ops/sec
lru_peek($cache, 'key');           # 60M+ ops/sec
lru_delete($cache, 'key');         # 60M+ ops/sec

DESCRIPTION

lru provides a fast Least Recently Used cache implemented in C. All operations are O(1) using a hash table for lookups and a doubly linked list for ordering.

When the cache reaches capacity, the least recently used entry is automatically evicted on the next set.

Performance

get/set: O(1) - hash lookup + list splice
exists/peek: O(1) - hash lookup only
delete: O(1) - hash delete + list remove

METHODS

lru::new($capacity)

Create a new LRU cache with the given maximum capacity.

$cache->set($key, $value)

Store a value. If key exists, updates value and promotes to front. If at capacity, evicts least recently used entry first.

$cache->get($key)

Retrieve a value and promote to front. Returns undef if not found.

$cache->peek($key)

Retrieve a value without promoting. Returns undef if not found.

$cache->exists($key)

Check if key exists. Does not promote.

$cache->delete($key)

Remove an entry. Returns the deleted value or undef.

$cache->size

Returns the current number of entries.

$cache->capacity

Returns the maximum capacity.

$cache->clear

Remove all entries.

$cache->keys

Returns all keys in order (most recent first).

$cache->oldest

my ($key, $value) = $cache->oldest;

Returns the key and value of the least recently used entry (the one that would be evicted next if the cache is full). Returns an empty list if the cache is empty.

$cache->newest

my ($key, $value) = $cache->newest;

Returns the key and value of the most recently used entry. Returns an empty list if the cache is empty.

FUNCTION-STYLE API

For maximum performance, import function-style ops:

use lru qw(import);

This exports the following functions into your namespace:

lru_set($cache, $key, $value)

Set a key/value pair. Returns the value. Approximately 70% faster than $cache->set(...).

lru_get($cache, $key)

Get a value, promoting to front. Returns undef if not found. Approximately 2x faster than $cache->get(...).

lru_exists($cache, $key)

Check if key exists. Does not promote. Approximately 2x faster than $cache->exists(...).

lru_peek($cache, $key)

Get a value without promoting. Returns undef if not found. Approximately 2x faster than $cache->peek(...).

lru_delete($cache, $key)

Delete a key. Returns the deleted value or undef. Approximately 2x faster than $cache->delete(...).

lru_oldest($cache)

my ($key, $value) = lru_oldest($cache);

Returns the key and value of the least recently used entry. Returns an empty list if the cache is empty.

lru_newest($cache)

my ($key, $value) = lru_newest($cache);