/ 
LNATION-0.05
/ lru

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).

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(...).

AUTHOR

LNATION <email@lnation.org>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.