hakmem/core/box/mid_cold_iface_v3.h

// mid_cold_iface_v3.h - Cold Interface for Mid/Pool v3
//
// 役割:
//   - L1 レベルの refill / retire 操作を定義
//   - Page carve / return
//   - RegionIdBox 登録 / 解除
//   - Phase MID-V3-1: インターフェース宣言のみ
#pragma once

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

#include "mid_hotbox_v3_box.h"

// ============================================================================
// Cold Interface Function Pointers (for future vtable support)
// ============================================================================

typedef MidPageDescV3* (*mid_cold_refill_fn)(MidHotBoxV3* hot, uint32_t class_idx);
typedef void (*mid_cold_retire_fn)(MidHotBoxV3* hot, MidPageDescV3* page);
typedef bool (*mid_cold_remote_push_fn)(MidPageDescV3* page, void* ptr, uint32_t tid);
typedef void (*mid_cold_remote_drain_fn)(MidHotBoxV3* hot);

typedef struct MidColdIfaceV3 {
    mid_cold_refill_fn      refill_page;
    mid_cold_retire_fn      retire_page;
    mid_cold_remote_push_fn remote_push;
    mid_cold_remote_drain_fn remote_drain;
} MidColdIfaceV3;

// ============================================================================
// Default Cold Interface (direct function calls)
// ============================================================================

/// Refill: Get a new page from segment/pool
/// @param hot: TLS HotBox context
/// @param class_idx: Size class index
/// @return: New page with freelist, or NULL on failure
MidPageDescV3* mid_cold_v3_refill_page(MidHotBoxV3* hot, uint32_t class_idx);

/// Retire: Return an empty page to segment/pool
/// @param hot: TLS HotBox context
/// @param page: Page to retire (must be empty)
void mid_cold_v3_retire_page(MidHotBoxV3* hot, MidPageDescV3* page);

/// Remote push: Push freed block to remote thread's page
/// @param page: Target page (owned by different thread)
/// @param ptr: Block to free
/// @param tid: Caller's thread ID
/// @return: true if push succeeded, false if local handling needed
bool mid_cold_v3_remote_push(MidPageDescV3* page, void* ptr, uint32_t tid);

/// Remote drain: Process blocks freed by other threads
/// @param hot: TLS HotBox context
void mid_cold_v3_remote_drain(MidHotBoxV3* hot);

// ============================================================================
// Segment Operations
// ============================================================================

/// Acquire a segment for the given class
/// @param class_idx: Size class index
/// @return: Segment pointer, or NULL on failure
MidSegmentV3* mid_segment_v3_acquire(int class_idx);

/// Carve a page from segment
/// @param seg: Segment to carve from
/// @param class_idx: Size class index
/// @return: New page descriptor, or NULL if segment exhausted
MidPageDescV3* mid_segment_v3_carve_page(MidSegmentV3* seg, int class_idx);

/// Return a page to segment
/// @param seg: Owning segment
/// @param page: Page to return
void mid_segment_v3_return_page(MidSegmentV3* seg, MidPageDescV3* page);

// ============================================================================
// Lane Operations
// ============================================================================

/// Refill lane from page
/// @param lane: TLS lane
/// @param page: Source page
/// @param batch_size: Number of items to transfer
void mid_lane_refill_from_page(MidLaneV3* lane, MidPageDescV3* page, uint32_t batch_size);

/// Flush lane back to page
/// @param lane: TLS lane
/// @param page: Target page
void mid_lane_flush_to_page(MidLaneV3* lane, MidPageDescV3* page);

// ============================================================================
// Page Operations
// ============================================================================

/// Build freelist for a page
/// @param page: Page descriptor
/// @return: Freelist head
void* mid_page_build_freelist(MidPageDescV3* page);

/// Push a block to page's freelist (thread-safe)
/// @param page: Target page
/// @param ptr: Block to push
void mid_page_push_free(MidPageDescV3* page, void* ptr);

/// Pop a block from page's freelist
/// @param page: Source page
/// @return: Block pointer, or NULL if empty
void* mid_page_pop_free(MidPageDescV3* page);