Home /Modules/impl/sleela_memmgr.h

sleela_memmgr.h

impl/core/sleela_memmgr.h · 104 line(s) · c

#ifndef SLEELA_MEMMGR_H
#define SLEELA_MEMMGR_H

/* ===========================================================================
 * sleela_memmgr -- the SLeeLa Memory Manager.
 *
 * A thin, OS-neutral memory manager that sits on top of the OS allocator
 * abstraction (sleela_memory.*) and adds *accounting* and *limits*:
 *
 *   * every allocation carries a small header recording its size, so free()
 *     and realloc() can update the running total exactly (no per-pointer table
 *     is needed);
 *   * live bytes, peak bytes, and live/total allocation counts are tracked;
 *   * an optional hard byte limit fails allocations closed (returns NULL)
 *     instead of letting an untrusted native workload exhaust the host;
 *   * the whole thing is thread-safe (a single manager mutex) so it can back
 *     the VM and a spawned native at the same time.
 *
 * The manager is *opt-in*. When disabled (the default), the wrappers forward
 * straight to sleela_memory with no accounting overhead, so linking the
 * manager in costs nothing until a --memory-manager flag (or an on-need
 * native launch) enables it.
 *
 * This is deliberately independent of the mark-sweep GC (runtime/garbage_-
 * collector.*) and the per-class quota supervisor (runtime/security_-
 * supervisor.*): those track *managed objects* and *class/role* budgets,
 * whereas this manager accounts for *raw process memory* -- exactly the axis
 * that matters when SLeeLa is asked to run an arbitrary native executable.
 * ===========================================================================
 */

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

#ifdef __cplusplus
extern "C" {
#endif

#define SLMM_MIN_MEMORY_BYTES (256ull * 1024ull * 1024ull) /* 256 MiB */
#define SLMM_MAX_MEMORY_BYTES (2048ull * 1024ull * 1024ull) /* 2 GiB */
#define SLMM_DEFAULT_MEMORY_BYTES SLMM_MAX_MEMORY_BYTES

/* Why the manager refused an allocation (readable via slmm_last_status). */
typedef enum {
    SLMM_OK = 0,          /* last allocation succeeded (or none yet)        */
    SLMM_DISABLED = 1,    /* manager disabled; call forwarded untracked     */
    SLMM_LIMIT = 2,       /* would exceed the configured hard byte limit    */
    SLMM_OOM = 3,         /* the underlying OS allocator returned NULL      */
    SLMM_OVERFLOW = 4     /* requested size + header overflowed size_t      */
} SLMMStatus;

typedef struct {
    int      enabled;         /* nonzero once slmm_enable() has run          */
    size_t   limit_bytes;     /* hard cap on live bytes, 0 == unlimited      */
    size_t   live_bytes;      /* bytes currently handed out (payload only)   */
    size_t   peak_bytes;      /* high-water mark of live_bytes               */
    size_t   live_allocs;     /* allocations not yet freed                   */
    uint64_t total_allocs;    /* cumulative successful allocations           */
    uint64_t total_frees;     /* cumulative frees                            */
    uint64_t refused;         /* allocations refused (limit/oom/overflow)    */
    SLMMStatus last_status;   /* result of the most recent alloc attempt     */
} SLMMStats;

/* Enable the process-wide manager with a hard limit on live bytes.
 * The configured limit is constrained to 256 MiB..2 GiB. A zero value selects
 * the default 2 GiB limit. Safe to call again to raise/lower the limit; resetting
 * counters is done by slmm_reset(). Returns 0 on success. */
int  slmm_enable(size_t limit_bytes);

/* Disable the manager. Memory already handed out stays valid and is still
 * freed correctly (the header is always present), but new allocations are no
 * longer counted or limited. */
void slmm_disable(void);

int    slmm_is_enabled(void);
size_t slmm_limit(void);
void   slmm_set_limit(size_t limit_bytes);
int    slmm_valid_limit(size_t limit_bytes);

/* Accounted allocation family. When the manager is disabled these still return
 * usable memory (so callers never branch), just without accounting. Every
 * pointer they return MUST be released with slmm_free / resized with
 * slmm_realloc -- never the raw C free(), because of the size header. */
void* slmm_alloc(size_t size);
void* slmm_calloc(size_t count, size_t size);
void* slmm_realloc(void* ptr, size_t size);
void  slmm_free(void* ptr);

/* Introspection. */
void       slmm_stats(SLMMStats* out);
SLMMStatus slmm_last_status(void);
const char* slmm_status_name(SLMMStatus status);
void       slmm_reset(void);   /* zero the counters (keeps enabled/limit)   */

/* Render a one-block human-readable report to a caller buffer; returns the
 * number of bytes that would be written (like snprintf). */
int slmm_format_report(char* buf, size_t cap);

#ifdef __cplusplus
}
#endif

#endif /* SLEELA_MEMMGR_H */