hakmem/core/box/tiny_ultra_tls_box.h

// tiny_ultra_tls_box.h - Phase TLS-UNIFY-1: Unified ULTRA TLS API
//
// Goal: Single API for C4-C7 ULTRA TLS operations
// Phase 1: Thin wrapper delegating to existing TinyC*UltraFreeTLS
// Phase 2: Replace with unified struct (1 cache line hot path)
//
#ifndef HAKMEM_TINY_ULTRA_TLS_BOX_H
#define HAKMEM_TINY_ULTRA_TLS_BOX_H

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

// ============================================================================
// TinyUltraTlsCtx - Unified TLS context (Phase TLS-UNIFY-2a + TLS-UNIFY-3)
// ============================================================================
//
// Phase 1: Thin wrapper delegating to per-class TLS (completed)
// Phase 2a: Unified struct with array magazines for C4-C6 (completed)
//           C7 remains in separate TinyC7Ultra box.
// Phase 3: C6 intrusive LIFO (current) - ENV gated
//
// Capacity constants
#define TINY_ULTRA_C4_CAP 64
#define TINY_ULTRA_C5_CAP 64
#define TINY_ULTRA_C6_CAP 128

typedef struct TinyUltraTlsCtx {
    // Hot line: counts (8B aligned)
    uint16_t c4_count;
    uint16_t c5_count;
    uint16_t c6_count;
    uint16_t _pad_count;

    // C6 intrusive LIFO head (Phase TLS-UNIFY-3)
    // Used when HAKMEM_TINY_C6_ULTRA_INTRUSIVE_FL=1
    void* c6_head;

    // Per-class segment ranges (learned on first free)
    uintptr_t c4_seg_base;
    uintptr_t c4_seg_end;
    uintptr_t c5_seg_base;
    uintptr_t c5_seg_end;
    uintptr_t c6_seg_base;
    uintptr_t c6_seg_end;

    // Per-class array magazines (C4/C5 always, C6 when intrusive OFF)
    void* c4_freelist[TINY_ULTRA_C4_CAP];   // 512B
    void* c5_freelist[TINY_ULTRA_C5_CAP];   // 512B
    void* c6_freelist[TINY_ULTRA_C6_CAP];   // 1024B (kept for ENV_OFF fallback)
    // Total: ~2KB per thread (acceptable for array magazine design)

    // Note: C7 is NOT included here - uses separate TinyC7Ultra box
} TinyUltraTlsCtx;

// ============================================================================
// Unified API
// ============================================================================

// Get TLS context (Phase 1: returns dummy, Phase 2: returns actual unified ctx)
TinyUltraTlsCtx* tiny_ultra_tls_ctx(void);

// Pop BASE pointer from TLS freelist (C4-C7)
// Returns: BASE pointer on hit, NULL on miss (caller should fallback)
// class_idx: 4, 5, 6, or 7
void* tiny_ultra_tls_pop(uint8_t class_idx);

// Push BASE pointer to TLS freelist (C4-C7)
// class_idx: 4, 5, 6, or 7
// base: BASE pointer (not user pointer)
void tiny_ultra_tls_push(uint8_t class_idx, void* base);

// Check if unified TLS is enabled (ENV gate)
static inline int tiny_ultra_tls_unified_enabled(void) {
    // Phase 1: Always enabled (thin wrapper mode)
    return 1;
}


#endif // HAKMEM_TINY_ULTRA_TLS_BOX_H