Loading...
Searching...
No Matches
static_lru_hash_map.h
Go to the documentation of this file.
/*
* This file is part of the Aaru Data Preservation Suite.
* Copyright (c) 2019-2026 Natalia Portillo.
*
* This library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of the
* License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
#ifndef LIBAARUFORMAT_STATIC_LRU_HASH_MAP_H
#define LIBAARUFORMAT_STATIC_LRU_HASH_MAP_H
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#ifndef STATIC_LRU_EVICTION_LOAD_FACTOR
#define STATIC_LRU_EVICTION_LOAD_FACTOR 0.90
#endif
#ifndef STATIC_LRU_TARGET_LOAD_FACTOR
#define STATIC_LRU_TARGET_LOAD_FACTOR 0.75
#endif
#ifndef STATIC_LRU_AGING_INTERVAL
#define STATIC_LRU_AGING_INTERVAL 100000
#endif
#ifndef STATIC_LRU_MIN_SIZE
#define STATIC_LRU_MIN_SIZE 1024
#endif
typedef struct
{
uint64_t key;
uint64_t value;
uint8_t access_count;
uint8_t _padding[7];
} lru_kv_pair_t;
typedef struct
{
lru_kv_pair_t *table;
size_t size;
size_t count;
size_t max_count;
size_t target_count;
uint32_t age_counter;
uint32_t _padding;
// Optional statistics (can be compiled out if not needed)
#ifdef STATIC_LRU_ENABLE_STATS
uint64_t total_lookups;
uint64_t cache_hits;
uint64_t total_inserts;
uint64_t eviction_count;
uint64_t eviction_cycles;
#endif
} static_lru_hash_map_t;
static_lru_hash_map_t *static_lru_create_map(size_t size);
void static_lru_free_map(static_lru_hash_map_t *map);
bool static_lru_insert_map(static_lru_hash_map_t *map, uint64_t key, uint64_t value);
bool static_lru_lookup_map(static_lru_hash_map_t *map, uint64_t key, uint64_t *out_value);
bool static_lru_contains_key(const static_lru_hash_map_t *map, uint64_t key);
size_t static_lru_evict(static_lru_hash_map_t *map, size_t entries_to_keep);
void static_lru_age_counts(static_lru_hash_map_t *map);
double static_lru_load_factor(const static_lru_hash_map_t *map);
size_t static_lru_free_slots(const static_lru_hash_map_t *map);
#ifdef STATIC_LRU_ENABLE_STATS
double static_lru_hit_rate(const static_lru_hash_map_t *map);
void static_lru_reset_stats(static_lru_hash_map_t *map);
#endif
#endif // LIBAARUFORMAT_STATIC_LRU_HASH_MAP_H
static_lru_free_map
void static_lru_free_map(static_lru_hash_map_t *map)
Frees all memory associated with a static LRU hash map.
Definition static_lru_hash_map.c:237
static_lru_age_counts
void static_lru_age_counts(static_lru_hash_map_t *map)
Manually ages all access counts.
Definition static_lru_hash_map.c:331
static_lru_free_slots
size_t static_lru_free_slots(const static_lru_hash_map_t *map)
Returns the number of free slots available.
Definition static_lru_hash_map.c:339
static_lru_create_map
static_lru_hash_map_t * static_lru_create_map(size_t size)
Creates a new static LRU hash map with fixed size.
Definition static_lru_hash_map.c:204
static_lru_evict
size_t static_lru_evict(static_lru_hash_map_t *map, size_t entries_to_keep)
Manually triggers eviction of least-used entries.
Definition static_lru_hash_map.c:328
static_lru_lookup_map
bool static_lru_lookup_map(static_lru_hash_map_t *map, uint64_t key, uint64_t *out_value)
Looks up a value by key in the static LRU hash map.
Definition static_lru_hash_map.c:284
static_lru_load_factor
double static_lru_load_factor(const static_lru_hash_map_t *map)
Returns the current load factor of the map.
Definition static_lru_hash_map.c:337
static_lru_insert_map
bool static_lru_insert_map(static_lru_hash_map_t *map, uint64_t key, uint64_t value)
Inserts a key-value pair into the static LRU hash map.
Definition static_lru_hash_map.c:245
static_lru_contains_key
bool static_lru_contains_key(const static_lru_hash_map_t *map, uint64_t key)
Checks if a key exists in the map WITHOUT updating access count.
Definition static_lru_hash_map.c:314
lru_kv_pair_t
Single key/value slot with access tracking for the static LRU hash map.
Definition static_lru_hash_map.h:72
lru_kv_pair_t::access_count
uint8_t access_count
Access frequency counter (0-255, saturates at 255).
Definition static_lru_hash_map.h:75
lru_kv_pair_t::_padding
uint8_t _padding[7]
Padding for 8-byte alignment (24 bytes total per entry).
Definition static_lru_hash_map.h:76
lru_kv_pair_t::value
uint64_t value
Associated value payload (64-bit).
Definition static_lru_hash_map.h:74
lru_kv_pair_t::key
uint64_t key
Stored key (64-bit). 0 indicates an empty slot.
Definition static_lru_hash_map.h:73
static_lru_hash_map_t
Fixed-size hash map with LRU-like eviction for bounded memory usage.
Definition static_lru_hash_map.h:98
static_lru_hash_map_t::max_count
size_t max_count
Eviction trigger threshold (size * EVICTION_LOAD_FACTOR).
Definition static_lru_hash_map.h:102
static_lru_hash_map_t::age_counter
uint32_t age_counter
Operations since last aging.
Definition static_lru_hash_map.h:104
static_lru_hash_map_t::target_count
size_t target_count
Target count after eviction (size * TARGET_LOAD_FACTOR).
Definition static_lru_hash_map.h:103
static_lru_hash_map_t::count
size_t count
Number of active (filled) entries.
Definition static_lru_hash_map.h:101
static_lru_hash_map_t::table
lru_kv_pair_t * table
Array of key/value slots of length == size.
Definition static_lru_hash_map.h:99
static_lru_hash_map_t::size
size_t size
Allocated slot capacity (FIXED at creation).
Definition static_lru_hash_map.h:100
static_lru_hash_map_t::_padding
uint32_t _padding
Padding for alignment.
Definition static_lru_hash_map.h:105