os_alloc.h

/*-
 * Copyright (c) 2026, The XTC Project
 * Use of this source code is governed by the ISC License.
 *
 * src/inc/os_alloc.h
 *      Hookable allocator abstraction.  Default backend is malloc(3);
 *      a vtable lets PG (or libumem, or jemalloc) substitute its own
 *      primitives.  See M1_CLAIMS.md, M1-M8.
 */
 
#ifndef XTC_OS_ALLOC_H
#define XTC_OS_ALLOC_H
 
#include "xtc_export.h"
 
#include <stddef.h>
 
/*
 * The allocator vtable.  All six callbacks must be set together; we
 * do not interleave callbacks from different backends.
 *
 * Contract on each callback:
 *      malloc(sz)       -> non-NULL pointer of >= sz bytes, or NULL on OOM.
 *      calloc(n, sz)    -> zeroed; return NULL on OOM or n*sz overflow.
 *      realloc(p, sz)   -> like malloc; if p != NULL, contents are preserved.
 *      free(p)          -> p may be NULL.
 *      aligned(a, sz)   -> a is a power of two and >= sizeof(void *); NULL on OOM.
 *      aligned_free(p)  -> frees memory from aligned(); p may be NULL.
 *
 * aligned() and aligned_free() are a matched pair: memory from
 * aligned() MUST be released with aligned_free(), never free().  On
 * some platforms (Windows _aligned_malloc) the two heaps are distinct
 * and crossing them corrupts the heap.
 *
 * __os_alloc_set_hook COPIES this structure, so it need not outlive
 * the call -- a stack local is fine.
 */
struct __os_alloc_hook {
        void *(*malloc)(size_t sz);
        void *(*calloc)(size_t n, size_t sz);
        void *(*realloc)(void *p, size_t sz);
        void  (*free)(void *p);
        void *(*aligned)(size_t align, size_t sz);
        void  (*aligned_free)(void *p);
};
 
/*
 * Public-internal API.  Every function returns an int status code
 * except __os_free which has no failure mode.
 *
 * PUBLIC: int  __os_malloc __P((size_t, void **));
 * PUBLIC: int  __os_calloc __P((size_t, size_t, void **));
 * PUBLIC: int  __os_realloc __P((void *, size_t, void **));
 * PUBLIC: size_t __os_msize __P((void *));
 * PUBLIC: void __os_free __P((void *));
 * PUBLIC: int  __os_strdup __P((const char *, char **));
 * PUBLIC: int  __os_aligned_alloc __P((size_t, size_t, void **));
 * PUBLIC: void __os_aligned_free __P((void *));
 * PUBLIC: int  __os_alloc_set_hook __P((const struct __os_alloc_hook *));
 * PUBLIC: int  __os_alloc_get_hook __P((struct __os_alloc_hook *));
 */
XTC_API int  __os_malloc(size_t sz, void **out);
XTC_API int  __os_calloc(size_t n, size_t sz, void **out);
XTC_API int  __os_realloc(void *p, size_t sz, void **out);
XTC_API size_t __os_msize(void *p);
XTC_API void __os_free(void *p);
XTC_API int  __os_strdup(const char *s, char **out);
XTC_API int  __os_aligned_alloc(size_t align, size_t sz, void **out);
XTC_API void __os_aligned_free(void *p);
XTC_API int  __os_alloc_set_hook(const struct __os_alloc_hook *hook);
XTC_API int  __os_alloc_get_hook(struct __os_alloc_hook *out);
 
#endif /* XTC_OS_ALLOC_H */