AxlCache – TTL Cache

TTL cache with LRU eviction. Fixed-size slots, string keys, opaque fixed-size values. Designed for single-threaded UEFI use.

Header: <axl/axl-cache.h>

Overview

AxlCache is a simple key-value store with time-based expiration and least-recently-used eviction when full. Values are copied into fixed-size slots (not stored as pointers).

Use cases: DNS resolution caching, HTTP response caching, SMBIOS lookup caching.

// Cache up to 16 entries, each 4 bytes (e.g., IPv4 addresses)
AXL_AUTOPTR(AxlCache) cache = axl_cache_new(16, sizeof(uint32_t), 60000);
//                                           ^    ^                ^
//                                     slots  value size      TTL (ms)

// Store a value
uint32_t addr = 0xC0A80101;  // 192.168.1.1
axl_cache_put(cache, "gateway", &addr);

// Retrieve
uint32_t result;
if (axl_cache_get(cache, "gateway", &result) == 0) {
    // hit -- result contains the cached value
}

// Invalidate a specific entry
axl_cache_invalidate(cache, "gateway");

// Invalidate all entries
axl_cache_invalidate_all(cache);

API Reference

Typedefs

typedef struct AxlCache AxlCache

Functions

AxlCache *axl_cache_new(size_t max_slots, size_t entry_size, uint64_t ttl_ms)

Create a new TTL cache.

Parameters:

  • max_slots – maximum number of cached entries

  • entry_size – size of each value in bytes

  • ttl_ms – time-to-live per entry in milliseconds

Returns:

new cache, or NULL on allocation failure. Free with axl_cache_free().

int axl_cache_put(AxlCache *c, const char *key, const void *value)

Store a value in the cache.

Copies value into the cache under key. If key already exists, the entry is refreshed. If the cache is full, the oldest (LRU) entry is evicted.

Parameters:

  • c – cache

  • key – string key (copied internally)

  • value – value to store (entry_size bytes copied)

Returns:

0 on success, -1 on error.

int axl_cache_get(AxlCache *c, const char *key, void *value)

Look up a value by key.

Copies the cached value into value if found and not expired. Expired entries are treated as misses and invalidated.

Parameters:

  • c – cache

  • key – string key

  • value – [out] receives entry_size bytes

Returns:

0 on hit, -1 on miss or error.

void axl_cache_invalidate(AxlCache *c, const char *key)

Invalidate a specific key. No-op if not found.

Parameters:

  • c – cache

  • key – key to remove

void axl_cache_free(AxlCache *c)

Free a cache and all its entries. NULL-safe.

Parameters:

  • c – cache to free