hakmem/core/box/tiny_next_ptr_box.h

#ifndef TINY_NEXT_PTR_BOX_H
#define TINY_NEXT_PTR_BOX_H

/**
 * 📦 Box: Next Pointer Operations (Lowest-Level API)
 *
 * Phase E1-CORRECT: Unified next pointer read/write API for ALL classes (C0-C7)
 *
 * This Box provides structural guarantee that ALL next pointer operations
 * use consistent offset calculation, eliminating scattered direct pointer
 * access bugs.
 *
 * Design:
 * - With HAKMEM_TINY_HEADER_CLASSIDX=1: Next pointer stored at base+1 (ALL classes)
 * - Without headers: Next pointer stored at base+0
 * - Inline expansion ensures ZERO performance cost
 *
 * Usage:
 *   void* next = tiny_next_read(class_idx, base_ptr);      // Read next pointer
 *   tiny_next_write(class_idx, base_ptr, new_next);        // Write next pointer
 *
 * Critical:
 * - ALL freelist operations MUST use this API
 * - Direct access like *(void**)ptr is PROHIBITED
 * - Grep can detect violations: grep -rn '\*\(void\*\*\)' core/
 */

#include <stdint.h>
#include <stdio.h>   // For debug fprintf
#include <stdatomic.h>  // For _Atomic
#include <stdlib.h>  // For abort()

/**
 * Write next pointer to freelist node
 *
 * @param class_idx Size class index (0-7)
 * @param base Base pointer (NOT user pointer)
 * @param next_value Next pointer to store (or NULL for list terminator)
 *
 * CRITICAL FIX: Class 0 (8B block) cannot fit 8B pointer at offset 1!
 * - Class 0: 8B total = [1B header][7B data] → pointer at base+0 (overwrite header when free)
 * - Class 1-6: Next at base+1 (after header)
 * - Class 7: Next at base+0 (no header in original design, kept for compatibility)
 *
 * NOTE: We take class_idx as parameter (NOT read from header) because:
 * - Linear carved blocks don't have headers yet (uninitialized memory)
 * - Class 0/7 overwrite header with next pointer when on freelist
 */
static inline void tiny_next_write(int class_idx, void* base, void* next_value) {
#if HAKMEM_TINY_HEADER_CLASSIDX
    // Phase E1-CORRECT FIX: Use class_idx parameter (NOT header byte!)
    // Reading uninitialized header bytes causes random offset calculation
    size_t next_offset = (class_idx == 0 || class_idx == 7) ? 0 : 1;

    // Direct write (header validation temporarily disabled to debug hang in drain phase)
    *(void**)((uint8_t*)base + next_offset) = next_value;
#else
    // No headers: Next pointer at base
    *(void**)base = next_value;
#endif
}

/**
 * Read next pointer from freelist node
 *
 * @param class_idx Size class index (0-7)
 * @param base Base pointer (NOT user pointer)
 * @return Next pointer (or NULL if end of list)
 */
static inline void* tiny_next_read(int class_idx, const void* base) {
#if HAKMEM_TINY_HEADER_CLASSIDX
    // Phase E1-CORRECT FIX: Use class_idx parameter (NOT header byte!)
    size_t next_offset = (class_idx == 0 || class_idx == 7) ? 0 : 1;

    // Direct read (corruption check temporarily disabled to debug hang in drain phase)
    return *(void**)((const uint8_t*)base + next_offset);
#else
    // No headers: Next pointer at base
    return *(void**)base;
#endif
}

#endif  // TINY_NEXT_PTR_BOX_H