ubgpsuite/lonetix/include/df/mem.h

86 lines
3.4 KiB
C

// SPDX-License-Identifier: LGPL-3.0-or-later
/**
* \file mem.h
*
* Common allocator interface.
*
* \copyright The DoubleFourteen Code Forge (C) All Rights Reserved
* \author Lorenzo Cogotti
*/
#ifndef DF_MEM_H_
#define DF_MEM_H_
#include "xpt.h"
/**
* \brief Memory allocator interface.
*
* This is a common interface `struct` used by functions or types
* that accomodate for custom memory allocation policies.
*
* \note The behavior described here for the `Alloc` and `Free` functions is
* a sensible contract that should be respected by most allocators.
* Still, special purpose allocators may tweak it to fit very
* specific situations, e.g. an allocator optimized for a specific use may
* ignore all calls to `Free`, or may interpret a `Free` of chunks never
* returned by `Alloc` as hints to grow its available memory pool,
* a sensitive allocator may choose to only return zeroed memory on
* new chunks and zero them out as soon as they're `Free`d.
* Such allocators should be restricted to special circumstances, while
* the behavior described here should provide the general rule.
*/
typedef struct {
/**
* \brief Allocate or reallocate a memory chunk.
*
* The `Alloc` function takes an optional `allocp`, which may represent
* the allocator state. Some allocators don't require any state or
* provide a global one, in which case `allocp` may be `NULL`.
* The returned chunk is required to be at least `size` bytes large.
* The `oldp` argument is `NULL` for new allocations, but may also be
* a pointer to an existing chunk previously returned by the allocator,
* which is the case for shrink or grow requests. The allocator may
* enlarge or shrink the chunk referenced by `oldp` to reduce
* fragmentation.
* On shrink and grow requests the data up to the minimum value between
* `size` and the old chunk size is preserved
*
* \param [in,out] allocp Allocator state pointer, `NULL` if allocator has no state
* \param [in] size Requested memory chunk size, in bytes
* \param [in,out] oldp Old memory chunk pointer, `NULL` if a new allocation is
* requested
*
* \return One of the following:
* * a pointer to a possibly uninitialized memory chunk on successful new
* allocation,
* * a pointer to the resized memory block, which may reside
* in a different location rather than `oldp`, in the event of
* a successful shrink or grow request,
* * `NULL` on allocation failure.
*/
void *(*Alloc)(void *allocp, size_t size, void *oldp);
/**
* \brief Free a memory chunk.
*
* The `Free` function takes an optional `allocp`, which may
* represent the allocator state, with the same semantics as `Alloc`,
* and a pointer previously returned by `Alloc`, and marks the chunk
* referenced by it as free for future allocations.
* Any allocator should silently ignore requests to free the `NULL`
* pointer.
*
* \param [in,out] allocp Allocator state pointer, `NULL` if allocator has no
* state
* \param [in] p Pointer to a memory chunk previously returned by `Alloc`,
* if `NULL` calling this function is a NOP.
*/
void (*Free)(void *allocp, void *p);
} MemOps;
/// Plain `MemOps` using regular `realloc()` and `free()`, use `NULL` for `allocp`.
extern const MemOps *const Mem_StdOps;
#endif