// ss_stats_box.h - SuperSlab Statistics Box
// Purpose: Global statistics tracking and reporting for SuperSlab allocations
// Box Theory: Centralized metrics collection with thread-safe updates
//
// Responsibilities:
//   - Track global allocation/free counts
//   - Track bytes allocated
//   - Per-class allocation statistics
//   - Statistics reporting (print functions)
//
// Dependencies: None (pure data collection)
//
// License: MIT
// Date: 2025-11-19

#ifndef HAKMEM_SS_STATS_BOX_H
#define HAKMEM_SS_STATS_BOX_H

#include <stdint.h>
#include <stddef.h>
#include <stdatomic.h>
#include "../superslab/superslab_types.h"

// ============================================================================
// Global Statistics (external visibility for tests/debugging)
// ============================================================================

extern uint64_t g_superslabs_allocated;  // Total SuperSlabs allocated
extern uint64_t g_superslabs_freed;      // Total SuperSlabs freed
extern uint64_t g_bytes_allocated;       // Total bytes allocated

extern uint64_t g_ss_alloc_by_class[8];  // Per-class allocation counts
extern uint64_t g_ss_freed_by_class[8];  // Per-class free counts

extern uint64_t g_superslabs_reused;     // Cache hit count
extern uint64_t g_superslabs_cached;     // Cache store count

// Debug counters (free path instrumentation)
extern _Atomic uint64_t g_ss_active_dec_calls;
extern _Atomic uint64_t g_hak_tiny_free_calls;
extern _Atomic uint64_t g_ss_remote_push_calls;
extern _Atomic uint64_t g_free_ss_enter;
extern _Atomic uint64_t g_free_local_box_calls;
extern _Atomic uint64_t g_free_remote_box_calls;

// ============================================================================
// Superslab / Slab live-state observability (Tiny classes 0..7)
// ============================================================================
// NOTE: These are “event-style” counters updated at key transitions
// (alloc/free/reset) to keep overhead minimal. They are intended for
// regression detection and coarse budgeting rather than exact gauges.
extern _Atomic uint64_t g_ss_live_by_class[8];   // +1 on alloc, -1 on free (best-effort)
extern _Atomic uint64_t g_ss_empty_events[8];    // Observations of fully-empty Superslabs
extern _Atomic uint64_t g_slab_live_events[8];   // Observations of live slabs during scans

// ============================================================================
// Statistics Update API
// ============================================================================

// Record OS allocation (new SuperSlab from mmap)
// Thread-safe: mutex protected
void ss_stats_os_alloc(uint8_t size_class, size_t ss_size);

// Record cache reuse (SuperSlab from LRU/prewarm cache)
// Thread-safe: mutex protected
void ss_stats_cache_reuse(void);

// Record cache store (SuperSlab stored in cache instead of munmap)
// Thread-safe: mutex protected
void ss_stats_cache_store(void);

// Event-style observability helpers (Tiny classes only, relaxed atomics)
void ss_stats_on_ss_alloc_class(int class_idx);
void ss_stats_on_ss_free_class(int class_idx);
void ss_stats_on_ss_scan(int class_idx, int slab_live, int is_empty);

// ============================================================================
// Statistics Reporting API
// ============================================================================

// Print per-SuperSlab statistics (for debugging)
void superslab_print_stats(SuperSlab* ss);

// Print global SuperSlab statistics
void superslab_print_global_stats(void);

// ENV: HAKMEM_SS_STATS_DUMP=1 → dump coarse Superslab/slab counters once
void ss_stats_dump_if_requested(void);

#endif // HAKMEM_SS_STATS_BOX_H