hakmem/core/hakmem_tiny_superslab.h

// hakmem_tiny_superslab.h - SuperSlab allocator for Tiny Pool (Phase 6.22)
// Purpose: mimalloc-inspired 2MB aligned slab allocation for fast pointer→slab lookup
// License: MIT
// Date: 2025-10-24
// Phase 6-2.8: Refactored into modular headers (types, inline)

#ifndef HAKMEM_TINY_SUPERSLAB_H
#define HAKMEM_TINY_SUPERSLAB_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <stdatomic.h>
#include <stdlib.h>
#include <time.h>  // Phase 8.3: For clock_gettime() in hak_now_ns()
#include <signal.h>
#include <stdio.h>  // For fprintf() debugging
#include <pthread.h>

// Phase 6-2.8: Modular headers (types, inline functions)
#include "superslab/superslab_types.h"
#include "superslab/superslab_inline.h"

// Legacy includes (for backward compatibility)
#include "tiny_debug_ring.h"
#include "tiny_remote.h"
#include "hakmem_tiny_superslab_constants.h"  // Phase 6-2.5: Centralized layout constants
#include "hakmem_build_flags.h"

// Debug instrumentation flags (defined in hakmem_tiny.c)
extern int g_debug_remote_guard;
extern int g_tiny_safe_free_strict;
extern _Atomic uint64_t g_ss_active_dec_calls;

uint32_t tiny_remote_drain_threshold(void);

// ============================================================================
// Tiny block stride helper (Phase 7 header-aware)
// ============================================================================
// Returns the effective per-block stride used for linear carving within slabs.
// When header-based class indexing is enabled, classes 0-6 reserve an extra
// byte per block for the header. Class 7 (1024B) remains headerless by design.
static inline size_t tiny_block_stride_for_class(int class_idx) {
    // Local size table (avoid extern dependency for inline function)
    static const size_t class_sizes[8] = {8, 16, 32, 64, 128, 256, 512, 1024};
    size_t bs = class_sizes[class_idx];
#if HAKMEM_TINY_HEADER_CLASSIDX
    // Phase E1-CORRECT: ALL classes have 1-byte header
    bs += 1;
#endif
#if !HAKMEM_BUILD_RELEASE
    // One-shot debug: confirm stride behavior at runtime for class 0
    static _Atomic int g_stride_dbg = 0;
    if (class_idx == 0) {
        int exp = 0;
        if (atomic_compare_exchange_strong(&g_stride_dbg, &exp, 1)) {
            fprintf(stderr, "[STRIDE_DBG] HEADER_CLASSIDX=%d class=%d stride=%zu\n",
                    (int)HAKMEM_TINY_HEADER_CLASSIDX, class_idx, bs);
        }
    }
#endif
    return bs;
}

// ============================================================================
// Phase 2a: Dynamic Expansion - Global per-class SuperSlabHeads
// ============================================================================

extern SuperSlabHead* g_superslab_heads[TINY_NUM_CLASSES_SS];

// ============================================================================
// SuperSlab Management Functions
// ============================================================================

// Allocate a new SuperSlab (2MB aligned)
SuperSlab* superslab_allocate(uint8_t size_class);

// Free a SuperSlab
void superslab_free(SuperSlab* ss);

// Phase 2a: Dynamic Expansion Functions
// Initialize SuperSlabHead for a class (called once per class)
SuperSlabHead* init_superslab_head(int class_idx);

// Expand SuperSlabHead by allocating and linking a new chunk
// Returns 0 on success, -1 on OOM
int expand_superslab_head(SuperSlabHead* head);

// Find which chunk a pointer belongs to
// Returns the chunk containing ptr, or NULL if not found
SuperSlab* find_chunk_for_ptr(void* ptr, int class_idx);

// Initialize a slab within SuperSlab
void superslab_init_slab(SuperSlab* ss, int slab_idx, size_t block_size, uint32_t owner_tid);

// Mark a slab as active
void superslab_activate_slab(SuperSlab* ss, int slab_idx);

// Mark a slab as inactive
void superslab_deactivate_slab(SuperSlab* ss, int slab_idx);

// Find first free slab index (-1 if none)
int superslab_find_free_slab(SuperSlab* ss);

// Statistics
void superslab_print_stats(SuperSlab* ss);

// Phase 8.3: ACE statistics
void superslab_ace_print_stats(void);

// ============================================================================
// Phase 8.3: ACE (Adaptive Cache Engine) - SuperSlab adaptive sizing
// ============================================================================

// ACE tick function (called periodically, ~150ms interval)
// Observes metrics and decides promotion (1MB→2MB) or demotion (2MB→1MB)
void hak_tiny_superslab_ace_tick(int class_idx, uint64_t now_ns);

// Phase 8.4: ACE Observer (called from Learner thread - zero hot-path overhead)
void hak_tiny_superslab_ace_observe_all(void);

// ============================================================================
// Partial SuperSlab adopt/publish (per-class single-slot)
// ============================================================================

// Publish a SuperSlab with available freelist for other threads to adopt.
void ss_partial_publish(int class_idx, SuperSlab* ss);

// Adopt published SuperSlab for the class (returns NULL if none).
SuperSlab* ss_partial_adopt(int class_idx);

// ============================================================================
// SuperSlab adopt gate (publish/adopt wiring helper)
// ============================================================================

// Environment-aware switch that keeps free/alloc sides in sync. Default:
//   - Disabled until cross-thread free is observed.
//   - `HAKMEM_TINY_SS_ADOPT=1` forces ON, `=0` forces OFF.
int tiny_adopt_gate_should_publish(void);
int tiny_adopt_gate_should_adopt(void);
void tiny_adopt_gate_on_remote_seen(int class_idx);

// ============================================================================
// External variable declarations
// ============================================================================

extern _Atomic int g_ss_remote_seen;  // set to 1 on first remote free observed
extern int g_remote_force_notify;

#endif // HAKMEM_TINY_SUPERSLAB_H