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