hakmem/core/box/superslab_expansion_box.h

// superslab_expansion_box.h - Box E: SuperSlab Expansion with TLS State Guarantee
// Purpose: Encapsulates SuperSlab chunk expansion with Design by Contract
// Box Theory: Provides ACID-like guarantees for TLS state during expansion
//
// Design Principles:
// 1. Complete encapsulation - all expansion logic lives here
// 2. TLS state guarantee - caller's TLS pointers remain valid after expansion
// 3. Thread-safe - mutex protection for concurrent expansion attempts
// 4. Atomic state transitions - no partial updates visible to caller
// 5. Debug validation - compile-time optional invariant checking
//
// License: MIT
// Date: 2025-11-12

#ifndef HAKMEM_SUPERSLAB_EXPANSION_BOX_H
#define HAKMEM_SUPERSLAB_EXPANSION_BOX_H

#include <stdint.h>
#include <stdbool.h>
#include "../superslab/superslab_types.h"  // SuperSlabHead, SuperSlab
#include "../tiny_tls.h"                   // TinyTLSSlab

// ============================================================================
// Box E: Type Definitions
// ============================================================================

// TLS state snapshot (immutable after capture)
typedef struct ExpansionTLSState {
    SuperSlab*     ss;         // Current SuperSlab (may change after expansion)
    TinySlabMeta*  meta;       // Current slab metadata
    uint8_t*       slab_base;  // Current slab base pointer
    uint8_t        slab_idx;   // Current slab index
    uint8_t        class_idx;  // Size class
    uint8_t        _pad[2];    // Padding
} ExpansionTLSState;

// Expansion operation result
typedef struct ExpansionResult {
    bool              success;     // true if expansion succeeded
    ExpansionTLSState new_state;   // New TLS state (valid only if success=true)
    int               error_code;  // Error code (0=success, -1=OOM, -2=invalid params)
} ExpansionResult;

// ============================================================================
// Box E: Core API - Design by Contract
// ============================================================================

// Capture current TLS state (immutable snapshot)
// Precondition:  class_idx < TINY_NUM_CLASSES_SS
// Postcondition: Returns snapshot of current TLS state
ExpansionTLSState expansion_capture_tls_state(uint8_t class_idx);

// Expand SuperSlabHead with TLS state guarantee
// Precondition:  head != NULL, class_idx < TINY_NUM_CLASSES_SS
// Postcondition: If success, new_state contains valid TLS pointers to expanded chunk
//                If failure, head->current_chunk unchanged
// Thread-safe:   Yes (mutex protected)
ExpansionResult expansion_expand_with_tls_guarantee(
    SuperSlabHead* head,
    uint8_t class_idx
);

// Apply new TLS state to current thread
// Precondition:  new_state is valid (from successful expansion), tls_array != NULL
// Postcondition: tls_array[class_idx] updated atomically
// Note: tls_array should be g_tls_slabs from the caller's context
void expansion_apply_tls_state(
    uint8_t class_idx,
    const ExpansionTLSState* new_state,
    TinyTLSSlab* tls_array  // Pointer to g_tls_slabs from caller
);

// ============================================================================
// Box E: High-Level API - One-Call Expansion
// ============================================================================

// Safe expansion: capture → expand → apply in one call
// Returns true if expansion succeeded, false on OOM or invalid params
// Thread-safe: Yes
//
// Parameters:
//   head: SuperSlabHead to expand
//   class_idx: Size class index
//   tls_array: Pointer to g_tls_slabs array (from caller's context)
//
// Usage:
//   extern __thread TinyTLSSlab g_tls_slabs[];  // In caller's scope
//   if (!expansion_safe_expand(head, class_idx, g_tls_slabs)) {
//       // Expansion failed (OOM)
//       return NULL;
//   }
//   // TLS state is now updated, reload local pointers
//   TinyTLSSlab* tls = &g_tls_slabs[class_idx];
//   SuperSlab* ss = tls->ss;
static inline bool expansion_safe_expand(SuperSlabHead* head, uint8_t class_idx, TinyTLSSlab* tls_array) {
    if (!head || class_idx >= TINY_NUM_CLASSES_SS || !tls_array) {
        return false;
    }

    ExpansionResult result = expansion_expand_with_tls_guarantee(head, class_idx);
    if (!result.success) {
        return false;
    }

    expansion_apply_tls_state(class_idx, &result.new_state, tls_array);
    return true;
}

// ============================================================================
// Box E: Debug & Validation (Conditional Compilation)
// ============================================================================

#if !defined(HAKMEM_BUILD_RELEASE) || defined(HAKMEM_EXPANSION_BOX_DEBUG)

// Validate TLS state invariants
// Returns true if all invariants hold, false otherwise
bool expansion_validate_tls_state(
    const ExpansionTLSState* state,
    const char* context  // For debug logging (e.g., "before_expansion")
);

// Verify expansion succeeded correctly
// Returns true if expansion is valid, false otherwise
bool expansion_verify_expansion(
    SuperSlabHead* head,
    const ExpansionTLSState* old_state,
    const ExpansionTLSState* new_state
);

// Log expansion event (debug only)
void expansion_log_event(
    const char* event,        // Event name (e.g., "START", "SUCCESS", "FAILURE")
    uint8_t class_idx,
    const ExpansionTLSState* state
);

#else

// No-op in release builds
#define expansion_validate_tls_state(state, context) ((void)0, true)
#define expansion_verify_expansion(head, old, new) ((void)0, true)
#define expansion_log_event(event, cls, state) ((void)0)

#endif

#endif // HAKMEM_SUPERSLAB_EXPANSION_BOX_H