// ss_os_acquire_box.h - SuperSlab OS Memory Acquisition Box
// Purpose: Low-level OS memory allocation (mmap/munmap) for SuperSlabs
// Box Theory: Encapsulates platform-specific aligned memory allocation
//
// Responsibilities:
//   - Aligned mmap allocation (2MB boundary)
//   - OOM diagnostics and error reporting
//   - Global mmap counters
//
// Dependencies: None (pure OS interface)
//
// License: MIT
// Date: 2025-11-19

#ifndef HAKMEM_SS_OS_ACQUIRE_BOX_H
#define HAKMEM_SS_OS_ACQUIRE_BOX_H

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

// ============================================================================
// Global Counters (for debugging/diagnostics)
// ============================================================================

extern _Atomic uint64_t g_ss_mmap_count;
extern _Atomic uint64_t g_final_fallback_mmap_count;

// ============================================================================
// OS Acquisition API
// ============================================================================

// Acquire aligned SuperSlab memory from OS via mmap
//
// Parameters:
//   size_class: Size class index (0-7, for statistics)
//   ss_size: SuperSlab size in bytes (e.g., 2^21 = 2MB)
//   ss_mask: Alignment mask (ss_size - 1)
//   populate: If true, use MAP_POPULATE to prefault pages
//
// Returns: Aligned pointer or NULL on OOM
//
// Guarantees:
//   - Returns NULL on OOM (never crashes)
//   - Returned pointer is aligned to ss_size boundary
//   - Logs OOM once per process (not spammy)
//   - Updates g_ss_mmap_count counter
//
// Thread-safe: Yes (no shared state mutations except atomic counters)
void* ss_os_acquire(uint8_t size_class, size_t ss_size, uintptr_t ss_mask, int populate);

#endif // HAKMEM_SS_OS_ACQUIRE_BOX_H