hakmem/core/box/prewarm_box.h

// prewarm_box.h - Box Prewarm
// Priority 3 Box: Safe TLS Cache Pre-warming
//
// Purpose:
//   - Simple, safe API for pre-warming TLS caches
//   - Hides complex initialization dependencies
//   - Uses Box Capacity Manager + Box Carve-Push for safety
//   - Prevents double-free bugs from initialization order issues
//
// Design:
//   - Wraps capacity_box + carve_push_box
//   - Handles SuperSlab allocation automatically
//   - Idempotent: safe to call multiple times
//   - Clear success/failure reporting

#ifndef HAKMEM_BOX_PREWARM_H
#define HAKMEM_BOX_PREWARM_H

#include <stdint.h>
#include <stdbool.h>

// ============================================================================
// Box Prewarm API
// ============================================================================

// Pre-warm TLS SLL cache for a class with N blocks
//
// What it does:
//   1. Ensures capacity system is initialized
//   2. Checks/allocates SuperSlab if needed
//   3. Atomically carves and pushes N blocks to TLS SLL
//
// Returns: actual count pushed
//   - On success: count (or less if capacity limit reached)
//   - On failure: 0
//
// Safety guarantees:
//   - No orphaned blocks (all-or-nothing carve-push)
//   - Correct initialization order
//   - Active counters updated atomically
//   - No double-free risk
//
// Thread-safe: uses TLS
// Idempotent: safe to call multiple times (subsequent calls are no-op if already full)
//
// Example:
//   box_prewarm_tls(5, 128);  // Pre-warm class 5 (256B) with 128 blocks
int box_prewarm_tls(int class_idx, int count);

// Check if prewarm is needed (TLS SLL is empty or below threshold)
// Returns: number of blocks to prewarm, or 0 if already warmed
int box_prewarm_needed(int class_idx, int target_count);

#endif // HAKMEM_BOX_PREWARM_H