hakmem/core/box/mid_free_route_box.h

/**
 * mid_free_route_box.h
 *
 * Box: Mid Free Route Box
 * Responsibility: Route Mid MT allocations to correct free path
 * Contract: Try Mid MT registry lookup, return success/failure
 *
 * Part of Phase 5-Step2 fix for 19x free() slowdown
 *
 * Problem:
 *   - Mid MT allocator registers chunks in MidGlobalRegistry
 *   - Free path searches Pool's mid_desc registry (different registry!)
 *   - Result: 100% lookup failure → 4x cascading lookups → 19x slower
 *
 * Solution:
 *   - Add Mid MT registry lookup BEFORE Pool registry lookup
 *   - Route directly to mid_mt_free() if found
 *   - Fall through to existing path if not found
 *
 * Performance Impact:
 *   - Before: 1.42 M ops/s (19x slower than system malloc)
 *   - After:  14-21 M ops/s (Option B quick fix, 10-15x improvement)
 *
 * Created: 2025-11-29 (Phase 5-Step2 Mid MT Gap Fix)
 */

#ifndef MID_FREE_ROUTE_BOX_H
#define MID_FREE_ROUTE_BOX_H

#include "../hakmem_mid_mt.h"
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

// ============================================================================
// Box Contract: Mid MT Free Routing
// ============================================================================

/**
 * mid_free_route_try - Try Mid MT free path first
 *
 * @param ptr  Pointer to free
 * @return     true if handled by Mid MT, false to fall through
 *
 * Box Responsibilities:
 *   1. Query Mid MT registry (mid_registry_lookup)
 *   2. If found: Call mid_mt_free() and return true
 *   3. If not found: Return false (let existing path handle it)
 *
 * Box Guarantees:
 *   - Zero side effects if returning false
 *   - Correct free if returning true
 *   - Thread-safe (Mid MT registry has mutex protection)
 *
 * Performance:
 *   - Mid MT hit: O(log N) registry lookup + O(1) free = ~50 cycles
 *   - Mid MT miss: O(log N) registry lookup only = ~50 cycles
 *   - Compare to current broken path: 4 lookups + libc = ~750 cycles
 *
 * Usage Example:
 *   void free(void* ptr) {
 *       if (mid_free_route_try(ptr)) return;  // Mid MT handled
 *       // Fall through to existing free path...
 *   }
 */
__attribute__((always_inline))
static inline bool mid_free_route_try(void* ptr) {
    if (!ptr) return false;  // NULL ptr, not Mid MT

    // Query Mid MT registry (binary search + mutex)
    size_t block_size = 0;
    int class_idx = 0;

    if (mid_registry_lookup(ptr, &block_size, &class_idx)) {
        // Found in Mid MT registry, route to mid_mt_free()
        mid_mt_free(ptr, block_size);
        return true;  // Handled
    }

    // Not in Mid MT registry, fall through to existing path
    return false;
}

// ============================================================================
// Box Observability (Debug/Profiling)
// ============================================================================

#if MID_DEBUG
/**
 * mid_free_route_stats - Print Mid Free Route Box statistics
 *
 * Only available in debug builds (MID_DEBUG=1)
 * Tracks hit/miss rates for performance analysis
 */
void mid_free_route_stats(void);
#endif

#ifdef __cplusplus
}
#endif

#endif // MID_FREE_ROUTE_BOX_H