// mid_hotbox_v3_box.h - Mid/Pool HotBox v3 (型スケルトン)
//
// 役割:
//   - MID v3 の Lane / Page / TLS コンテキスト型と API 宣言を定義する箱。
//   - RegionIdBox 統合を前提とした設計。
//   - Phase MID-V3-1: 型スケルトンのみ（実装は後続フェーズ）
#pragma once

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

#include "tiny_geometry_box.h"

#ifndef MID_V3_NUM_CLASSES
#define MID_V3_NUM_CLASSES TINY_NUM_CLASSES
#endif

// Forward declarations
struct MidSegmentV3;

// ============================================================================
// MidPageDescV3: Page metadata for v3 HotBox
// ============================================================================
// Design note: Lane vs Page 二重管理を回避するため、
// freelist は Page に authoritative として保持し、
// Lane は TLS cache として機能する。

typedef struct MidPageDescV3 {
    uint8_t*  base;           // Page base address
    void*     freelist;       // Authoritative freelist
    uint32_t  capacity;       // Total slots
    uint32_t  used;           // Used count
    uint32_t  region_id;      // RegionIdBox registration ID (0 = not registered)
    uint32_t  block_size;     // Block size in bytes
    uint8_t   class_idx;      // Size class index
    uint8_t   flags;          // Page state flags
    uint16_t  reserved;       // Alignment padding
    void*     slab_ref;       // Underlying slab/segment reference
    struct MidSegmentV3* segment;  // Owning segment (NULL if legacy path)
    struct MidPageDescV3* next;    // Intrusive list linkage
} MidPageDescV3;

// Page flags
#define MID_PAGE_FLAG_ACTIVE   (1u << 0)  // Page is in active use
#define MID_PAGE_FLAG_PARTIAL  (1u << 1)  // Page has free slots
#define MID_PAGE_FLAG_FULL     (1u << 2)  // Page is exhausted
#define MID_PAGE_FLAG_RETIRED  (1u << 3)  // Page returned to cold

// ============================================================================
// MidLaneV3: TLS lane (per-class freelist cache)
// ============================================================================
// Design note: Lane は Page への index と freelist snapshot を保持。
// freelist_head は TLS 内でのみ有効な cache であり、
// 実際の freelist は MidPageDescV3.freelist にある。

typedef struct MidLaneV3 {
    uint32_t page_idx;        // Current working page index (0 = none)
    void*    freelist_head;   // TLS-local freelist snapshot
    uint32_t freelist_count;  // Remaining items in cache
    uint32_t alloc_count;     // Allocation count (stats)
    uint32_t free_count;      // Free count (stats)
} MidLaneV3;

// ============================================================================
// MidHotBoxV3: TLS heap context (per-thread)
// ============================================================================

typedef struct MidHotBoxV3 {
    MidLaneV3 lanes[MID_V3_NUM_CLASSES];
    uint32_t  tid;            // Thread ID (for remote free detection)
    uint32_t  flags;          // Context flags
} MidHotBoxV3;

// Context flags
#define MID_CTX_FLAG_INIT      (1u << 0)  // Context initialized

// ============================================================================
// MidSegmentV3: Segment descriptor (shared across threads)
// ============================================================================

typedef struct MidSegmentV3 {
    uintptr_t base;           // Segment base address
    size_t    size;           // Segment size in bytes
    uint32_t  magic;          // Validation magic number
    uint32_t  num_pages;      // Total pages in segment
    uint32_t  region_id;      // RegionIdBox registration ID
    uint8_t   class_idx;      // Primary class (or 0xFF for mixed)
    uint8_t   flags;          // Segment flags
    uint16_t  reserved;
    // page_meta[] follows (flexible array member)
} MidSegmentV3;

#define MID_SEGMENT_V3_MAGIC   0xCAFEBABE
#define MID_SEGMENT_V3_SIZE    (2 * 1024 * 1024)   // 2 MiB default
#define MID_PAGE_V3_SIZE       (64 * 1024)         // 64 KiB page
#define MID_PAGE_V3_SHIFT      16                  // log2(64 KiB)
#define MID_PAGES_PER_SEGMENT  (MID_SEGMENT_V3_SIZE / MID_PAGE_V3_SIZE)

// ============================================================================
// API Declarations (stubs for MID-V3-1)
// ============================================================================

/// Get TLS HotBox context
MidHotBoxV3* mid_hot_box_v3_get(void);

/// Allocation fast path
void* mid_hot_v3_alloc(MidHotBoxV3* hot, int class_idx);

/// Free fast path
void mid_hot_v3_free(void* ptr);

/// Check if v3 can own this pointer
int mid_hotbox_v3_can_own(int class_idx, void* ptr);

/// Page index conversion helpers
static inline uint32_t mid_page_to_idx(MidPageDescV3* page) {
    // Stub: actual implementation depends on segment layout
    (void)page;
    return 0;
}

static inline MidPageDescV3* mid_page_from_idx(uint32_t idx) {
    // Stub: actual implementation depends on segment layout
    (void)idx;
    return NULL;
}