/**
 * cache.h — Web服务器 LRU 缓存模块
 *
 * 设计思想:
 *   使用 哈希表 + 双向链表 实现 O(1) 的查找、插入和淘汰操作。
 *   哈希表提供快速键值查找，双向链表维护 LRU 访问顺序。
 *   最近被访问的节点移动到链表头部 (MRU位置)，
 *   链表尾部的节点是最久未被访问的 (LRU位置)，淘汰时优先移除。
 *
 * 数据结构:
 *   cache_entry: 单个缓存条目 (文件名、文件内容、大小、MIME类型、时间戳)
 *   cache_t:      缓存管理器 (哈希表桶数组、链表头尾、统计计数器)
 *
 * 主要操作:
 *   cache_init(max_size):  初始化缓存，设置最大条目数
 *   cache_lookup(url, buf, size, type): 查找缓存，命中时拷贝数据并返回 1
 *   cache_insert(url, data, size, type): 插入缓存，必要时淘汰 LRU 条目
 *   cache_free():           释放所有缓存内存
 */

#ifndef _CACHE_H_
#define _CACHE_H_

#include <time.h>
#include <pthread.h>

/* 缓存条目 */
typedef struct cache_entry {
    char *url;                  /* 请求 URL (作为键) */
    char *data;                 /* 文件内容 */
    long size;                  /* 文件大小 */
    char filetype[64];          /* MIME 类型 */
    struct timespec timestamp;  /* 最后访问时间 */
    struct cache_entry *prev;   /* 双向链表前驱 */
    struct cache_entry *next;   /* 双向链表后继 */
    struct cache_entry *hnext;  /* 哈希桶内链表 (冲突链) */
} cache_entry_t;

/* 缓存管理器 */
typedef struct {
    cache_entry_t **buckets;    /* 哈希桶数组 */
    int num_buckets;            /* 哈希桶数量 */
    int max_size;               /* 最大条目数 */
    int cur_size;               /* 当前条目数 */
    cache_entry_t *head;        /* LRU 链表头 (最近使用) */
    cache_entry_t *tail;        /* LRU 链表尾 (最久未使用) */
    pthread_mutex_t lock;       /* 线程安全锁 */

    /* 统计信息 */
    long long hits;             /* 缓存命中次数 */
    long long misses;           /* 缓存未命中次数 */
    long long evictions;        /* 淘汰次数 */
    long long bytes_served;     /* 从缓存服务的字节数 */
} cache_t;

/**
 * cache_init — 初始化 LRU 缓存
 * @max_size: 最大缓存条目数
 * @return: 指向 cache_t 的指针，失败返回 NULL
 */
cache_t *cache_init(int max_size);

/**
 * cache_lookup — 在缓存中查找 URL
 * @cache:    缓存管理器指针
 * @url:      请求的 URL 键
 * @data:     输出参数，命中时指向缓存数据的拷贝 (调用者需 free)
 * @size:     输出参数，数据大小
 * @filetype: 输出参数，MIME 类型
 * @return:   1=命中, 0=未命中
 */
int cache_lookup(cache_t *cache, const char *url,
                 char **data, long *size, char *filetype);

/**
 * cache_insert — 向缓存插入新条目
 * @cache:    缓存管理器指针
 * @url:      URL 键
 * @data:     文件内容 (缓存会拷贝一份)
 * @size:     文件大小
 * @filetype: MIME 类型
 * @return:   0=成功, -1=失败
 */
int cache_insert(cache_t *cache, const char *url,
                 const char *data, long size, const char *filetype);

/**
 * cache_free — 释放所有缓存资源
 */
void cache_free(cache_t *cache);

#endif /* _CACHE_H_ */