hakmem/core/box/warm_pool_prefill_box.h

// warm_pool_prefill_box.h - Warm Pool Prefill Box
// Purpose: Secondary prefill optimization - load multiple superlslabs when pool is empty
// License: MIT
// Date: 2025-12-04

#ifndef HAK_WARM_POOL_PREFILL_BOX_H
#define HAK_WARM_POOL_PREFILL_BOX_H

#include <stdint.h>
#include "../hakmem_tiny_config.h"
#include "../hakmem_tiny_superslab.h"
#include "../tiny_tls.h"
#include "../front/tiny_warm_pool.h"
#include "../box/warm_pool_stats_box.h"

// Forward declarations
extern __thread TinyTLSSlab g_tls_slabs[TINY_NUM_CLASSES];
extern SuperSlab* superslab_refill(int class_idx);

// ============================================================================
// Warm Pool Prefill Policy
// ============================================================================

// Prefill budget: How many additional SuperSlabs to load when pool is empty
// - If pool is empty, load PREFILL_BUDGET extra slabs to build working set
// - This avoids repeated registry scans on rapid cache misses
// - Set to 2 to balance between prefill lock overhead and pool depletion
#define WARM_POOL_PREFILL_BUDGET 2

// ============================================================================
// Warm Pool Prefill API (Inline for Cold Path)
// ============================================================================

// Perform secondary prefill when warm pool becomes empty
// Called from unified_cache_refill() cold path when warm_pool_count() == 0
//
// Algorithm:
//   1. Check if pool is empty
//   2. If yes, load PREFILL_BUDGET additional superlslabs via superslab_refill
//   3. Push all but the last to warm pool
//   4. Return the last one for immediate carving (in tls->ss)
//
// Returns: 0 on success, -1 if superslab_refill fails
//
// Performance: Only triggered when pool is empty, cold path cost
//
static inline int warm_pool_do_prefill(int class_idx, TinyTLSSlab* tls) {
    int budget = (tiny_warm_pool_count(class_idx) == 0) ? WARM_POOL_PREFILL_BUDGET : 1;

    while (budget > 0) {
        if (!tls->ss) {
            // Need to load a new SuperSlab
            if (!superslab_refill(class_idx)) {
                return -1;  // Error: cannot allocate new SuperSlab
            }
            tls = &g_tls_slabs[class_idx];  // Reload TLS after refill
        }

        // Check SuperSlab validity
        if (!(tls->ss && tls->ss->magic == SUPERSLAB_MAGIC)) {
            break;
        }

        if (budget > 1) {
            // Prefill mode: push to pool and load another
            tiny_warm_pool_push(class_idx, tls->ss);
            warm_pool_record_prefilled(class_idx);
            tls->ss = NULL;  // Force next iteration to refill
            budget--;
        } else {
            // Final slab: keep in TLS for immediate carving
            budget = 0;
        }
    }

    return 0;  // Success
}

#endif // HAK_WARM_POOL_PREFILL_BOX_H