malunal/allocators
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reworked, no version bump

Browse Source
This commit is contained in:
SoraKatadzuma
2026-08-12 19:47:59 -05:00
parent f82f8288cf
commit 70638a9b46
13 changed files with 1170 additions and 1383 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/malunal/allocators.h
+157 -313
View File
@@ -24,13 +24,34 @@
*/
#define NULL_ADDRESS ((void*)0)
// Assuring that ALLOCATOR_SIZE is correct.
#ifdef ALLOCATOR_SIZE
#undef ALLOCATOR_SIZE
#endif /* ALLOCATOR_SIZE */
/**
* @def ALLOCATOR_SIZE
* @brief Defines the size of allocators such that it can exist on the stack
* without the need to heap allocate it.
* @details This is defined based on the number of bytes of a pointer for the
* system and the number of members within the internal allocator
* implementation. It is statically asserted during compile to assure
* it is not wrong.
*/
#define ALLOCATOR_SIZE sizeof(malunal_size_t) * 7
/**
* @brief Defines the basis of all allocators.
* @details You can create new allocators simply by providing your own virtual
* function table, an optional upstream allocator, and the allocator
* context.
* @details This is a stack allocated opaque pointer to the internals. It is not
* meant to be extensible outside of this library, as this library
* should be capable of providing any and all possibly needed allocator
* and allocation strategies required.
*/
typedef struct Allocator allocator_t;
typedef struct {
malunal_uint8_t __opaque[ALLOCATOR_SIZE];
} allocator_t;
/**
* @brief A pointer to a mutable allocator.
@@ -52,20 +73,20 @@ typedef const allocator_t* allocator_iptr_t;
* @details These are extremely useful for debugging an allocator or catching
* runtime issues that can be fixed.
*/
typedef enum AllocatorException {
typedef enum {
/**
* @brief No exception was thrown.
* @details Some allocator functions only return an exception. This indicates
* for those functions that the operation was successful.
*/
ALLOCATOR_EXCEPTION_SUCCESS,
ALLOCATION_ERROR_SUCCESS,
/**
* @brief The generic allocator exception.
* @details If the allocator does not know what to throw, or in test cases,
* this may be thrown.
*/
ALLOCATOR_EXCEPTION_FAILURE,
ALLOCATION_ERROR_FAILURE,
/**
* @brief The allocator instance was null.
@@ -73,7 +94,7 @@ typedef enum AllocatorException {
* large object. So, when the reference is expected to be non-null,
* which is always, this will be thrown.
*/
ALLOCATOR_EXCEPTION_NULL_ALLOCATOR,
ALLOCATION_ERROR_NULL_ALLOCATOR,
/**
* @brief The allocator upstream was null.
@@ -81,7 +102,7 @@ typedef enum AllocatorException {
* to pointer to a valid allocator. For those allocators that expect
* an upstream, and do not receive it, this will be thrown.
*/
ALLOCATOR_EXCEPTION_NULL_UPSTREAM,
ALLOCATION_ERROR_NULL_UPSTREAM,
/**
* @brief The allocator context was null.
@@ -89,14 +110,14 @@ typedef enum AllocatorException {
* to point to a valid address. For those allocators that expect a
* context, and do not receive it, this will be thrown.
*/
ALLOCATOR_EXCEPTION_NULL_CONTEXT,
ALLOCATION_ERROR_NULL_CONTEXT,
/**
* @brief The allocator ran out of memory.
* @details By nature of memory being a limited resource, if the system or the
* allocator run out of memory this will be thrown.
*/
ALLOCATOR_EXCEPTION_OUT_OF_MEMORY,
ALLOCATION_ERROR_OUT_OF_MEMORY,
/**
* @brief The address being released does not belong to the allocator.
@@ -104,7 +125,7 @@ typedef enum AllocatorException {
* itself. Most allocators can check if it was allocated from its
* memory pool, and if it wasn't this will be thrown.
*/
ALLOCATOR_EXCEPTION_NOT_MY_ADDRESS,
ALLOCATION_ERROR_NOT_MY_ADDRESS,
/**
* @brief The allocator has determined that memory is being leaked.
@@ -112,91 +133,8 @@ typedef enum AllocatorException {
* some memory is still in use upon release or finalization. If this
* happens, the allocator may throw this exception.
*/
ALLOCATOR_EXCEPTION_LEAKY_MEMORY,
} allocator_exception_t;
/**
* @brief Packs together the information needed to initialize an allocator.
* @details By using a struct like this, we can easily indicate what parameters
* are being passed into the function.
*/
typedef struct AllocatorInitializeRequest {
/**
* @brief The allocator to initialize.
* @details There is a sort of double dispatch methodology with allocators.
* The primary @c allocator_initialize function will simply call into
* the provided allocators virtual function table, passing this data
* to it. This makes it possible for the virtual function to interact
* with the entirety of the allocator as if inherited.
*/
allocator_mptr_t allocator;
/**
* @brief The upstream allocator for allocator being initialized.
* @details This allows the allocator to get large memory allocations from an
* upstream allocator, such that it can partition those larger memory
* blocks.
*/
allocator_mptr_t upstream;
/**
* @brief The size to initialize the allocator to.
* @details It's useful for an allocator to be initialized to some initial
* size so that it can immediately begin to hand out allocated
* addresses.
*/
malunal_size_t size;
} allocator_initialize_req_t;
/**
* @brief A type definition for a pointer to a function that can initialize
* some allocator instance.
* @param request Contains the information necessary to fulfill the request.
* @returns @c ALLOCATOR_EXCEPTION_SUCCESS if the request could be fulfilled;
* otherwise, any other exception value.
*/
typedef allocator_exception_t
(*allocator_initialize_pfn_t)(
allocator_initialize_req_t request
);
/**
* @brief A type definition for a pointer to a function that can finalize some
* allocator instance.
* @param allocator The allocator to finalize.
* @returns @c ALLOCATOR_EXCEPTION_SUCCESS if the allocator could be finalized;
* otherwise, any other exception value.
*/
typedef allocator_exception_t
(*allocator_finalize_pfn_t)(
allocator_mptr_t allocator
);
/**
* @brief Packs together the information needed to acquire some memory.
* @details By using a struct like this, we can easily indicate what parameters
* are being passed into the function.
*/
typedef struct AllocatorAcquireRequest {
/**
* @brief The allocator to use to acquire the memory.
* @details There is a sort of double dispatch methodology with allocators.
* The primary @c allocator_acquire function will simply call into
* the provided allocators virtual function table, passing this data
* to it. This makes it possible for the virtual function to interact
* with the entirety of the allocator as if inherited.
*/
allocator_mptr_t allocator;
/**
* @brief The size of the allocation to acquire.
* @details Allocators need this to obtain a memory block. Allocators may also
* use it to perform bounds checking, update internals, or otherwise.
*/
malunal_size_t size;
} allocator_acquire_req_t;
ALLOCATION_ERROR_LEAKY_MEMORY,
} allocation_error_t;
/**
* @brief Represents the result of an acquisition request.
@@ -204,11 +142,11 @@ typedef struct AllocatorAcquireRequest {
* exception. Which part is put into the result is indicated by the
* @c threw tag.
*/
typedef struct AllocatorAcquireResult {
typedef struct {
/**
* @brief Indicates whether the result contains an allocation or exception.
* @details Allocators will set this to true when an exception has occurred,
* such as when there is no more memory to allocate from.
* @brief Indicates whether the result contains an allocation or an error.
* @details Allocators will set this to true when an error has occurred, such
* as when there is no more memory to allocate from.
*/
malunal_bool_t threw;
@@ -225,248 +163,145 @@ typedef struct AllocatorAcquireResult {
* @details If the allocator unsuccessfully fulfilled the request, this will
* contain the reason for failure.
*/
allocator_exception_t exception;
allocation_error_t error;
};
} allocator_acquire_res_t;
} allocation_result_t;
/**
* @brief A type definition of a pointer to a function that can acquire some
* newly allocated memory address.
* @param request Contains the information necessary to fulfill the request.
* @returns The result of acquisition which indicates if the function threw or
* if the request was fulfilled along with the exception or allocation.
* @brief Gets the upstream allocator of the provided allocator.
* @param allocator A pointer to the allocator.
* @param out A pointer to where to store the upstream allocator.
* @returns An error if the allocator could not provide the upstream allocator;
* otherwise, @c ALLOCATION_ERROR_SUCCESS.
*/
typedef allocator_acquire_res_t
(*allocator_acquire_pfn_t)(
allocator_acquire_req_t request
allocation_error_t
allocator_upstream(
allocator_mptr_t allocator,
allocator_mptr_t* out
);
/**
* @brief Packs together the information needed to reacquire some memory.
* @details By using a struct like this, we can easily indicate what parameters
* are being passed into the function.
* @brief Gets the number of bytes allocated by the allocator.
* @param allocator A pointer to the allocator.
* @param out A pointer to where to store the allocated count.
* @returns An error if the allocator could not provide the number of allocated
* bytes; otherwise, @c ALLOCATION_ERROR_SUCCESS.
*/
typedef struct AllocatorReacquireRequest {
/**
* @brief The allocator to use to reacquire the memory.
* @details There is a sort of double dispatch methodology with allocators.
* The primary @c allocator_acquire function will simply call into
* the provided allocators virtual function table, passing this data
* to it. This makes it possible for the virtual function to interact
* with the entirety of the allocator as if inherited.
*/
allocator_mptr_t allocator;
/**
* @brief The address of the previous allocation.
* @details The memory at this address will typically be released after its
* contents are copied to the new address, but some allocators will
* not fully release it, only soft release it.
*/
malunal_mptr_t prev;
/**
* @brief The size of the allocation to release.
* @details Allocators need this to release a memory block. Allocators may
* also use it to perform bounds checking, update internals, or
* otherwise.
*/
malunal_size_t oldsz;
/**
* @brief The size of the allocation to reacquire.
* @details Allocators need this to obtain a memory block. Allocators may also
* use it to perform bounds checking, update internals, or otherwise.
*/
malunal_size_t newsz;
} allocator_reacquire_req_t;
/**
* @brief A type definition of a pointer to a function that can reacquire some
* newly allocated memory address.
* @param request Contains the information necessary to fulfill the request.
* @returns The result of reacquisition which indicates if the function threw or
* if the request was fulfilled along with the exception or allocation.
*/
typedef allocator_acquire_res_t
(*allocator_reacquire_pfn_t)(
allocator_reacquire_req_t request
allocation_error_t
allocator_allocated_bytes(
allocator_mptr_t allocator,
malunal_size_t* out
);
/**
* @brief Packs together the information needed to release some memory.
* @details By using a struct like this, we can easily indicate what parameters
* are being passed into the function.
* @brief Gets the number of bytes reserved by the allocator.
* @param allocator A pointer to the allocator.
* @param out A pointer to where to store the reserved count.
* @returns An error if the allocator could not provide the number of reserved
* bytes; otherwise, @c ALLOCATION_ERROR_SUCCESS.
*/
typedef struct AllocatorReleaseRequest {
/**
* @brief The allocator to use to release the memory.
* @details There is a sort of double dispatch methodology with allocators.
* The primary @c allocator_release function will simply call into
* the provided allocators virtual function table, passing this data
* to it. This makes it possible for the virtual function to interact
* with the entirety of the allocator as if inherited.
*/
allocator_mptr_t allocator;
/**
* @brief The address of the allocation to release.
* @details The address can be null, as most allocators will simply ignore it.
* However, when the address is not null, it should be aligned unless
* an allocator explicitly requires an address to be unaligned.
*/
malunal_mptr_t address;
/**
* @brief The size of the allocation to release.
* @details Allocators need this to release a memory block. Allocators may
* also use it to perform bounds checking, update internals, or
* otherwise.
*/
malunal_size_t size;
} allocator_release_req_t;
/**
* @brief A type definition of a pointer to a function that can release some
* previously allocated memory address.
* @param request
*/
typedef allocator_exception_t
(*allocator_release_pfn_t)(
allocator_release_req_t request
allocation_error_t
allocator_reserved_bytes(
allocator_mptr_t allocator,
malunal_size_t* out
);
/**
* @brief Gets the number of times @c acquires was called on the allocator.
* @param allocator A pointer to the allocator.
* @param out A pointer to where to store the count.
* @returns An error if the allocator could not provide the number of times that
* @c acquire was called; otherwise, @c ALLOCATION_ERROR_SUCCESS.
*/
allocation_error_t
allocator_acquires_count(
allocator_mptr_t allocator,
malunal_size_t* out
);
/**
* @brief Defines the basis of all allocators.
* @details You can create new allocators simply by providing your own virtual
* function table, an optional upstream allocator, and the allocator
* context.
* @brief Gets the number of times @c release was called on the allocator.
* @param allocator A pointer to the allocator.
* @param out A pointer to where to store the count.
* @returns An error if the allocator could not provide the number of times that
* @c release was called; otherwise, @c ALLOCATION_ERROR_SUCCESS.
*/
struct Allocator {
/**
* @brief The virtual function table for the allocator.
* @details Contains the pointers to the functions that make this allocator
* struct effectively an interface.
*/
struct {
/**
* @brief The initialization funciton for a given allocator.
* @details This is responsible for initializing an allocator, which may
* include acquiring some memory from an upstream allocator or
* otherwise.
*/
const allocator_initialize_pfn_t initialize;
allocation_error_t
allocator_releases_count(
allocator_mptr_t allocator,
malunal_size_t* out
);
/**
* @brief The finalization function for a given allocator.
* @details This is responsible for finalizing an allocator, which may
* include releasing some memory to an upstream allocator or
* otherwise.
*/
const allocator_finalize_pfn_t finalize;
/**
* @brief The acquisition function for a given allocator.
* @details This is responsible for acquiring a new valid memory address for
* the calling code to use.
*/
const allocator_acquire_pfn_t acquire;
/**
* @brief The reacquisition function for a given allocator.
* @details This is responsible for acquiring a new valid memory address for
* the calling code, copying the old contents over to the new address
* automatically for the caller.
*/
const allocator_reacquire_pfn_t reacquire;
/**
* @brief The release function for a given allocator.
* @details This is responsible for releasing a previously allocated memory
* address. The caller is expected to destroy anything within the
* valid address.
*/
const allocator_release_pfn_t release;
} const vtable;
/**
* @brief The upstream allocator to this allocator.
* @details The purpose of an upstream allocator is to provide this allocator
* the ability to obtain other memory pages or blocks that it plans
* to further partition.
*/
allocator_mptr_t upstream;
/**
* @brief The context data for the allocator.
* @details This is passed to the allocator implementation through the vtable
* functions for the ability of the implementation to access its own
* data in the virtual functions.
*/
malunal_mptr_t context;
/**
* @brief How much of the reserved memory has been allocated.
* @details This is a piece of diagnostics that might be useful to know how
* much memory is being allocated by this allocator.
*/
malunal_size_t allocated;
/**
* @brief How much memory was reserved by this allocator.
* @details This is a piece of diagnostics that might be useful to know how
* much memory is being reserved by this allocator.
*/
malunal_size_t reserved;
/**
* @brief How many times this allocator was acquired from.
* @details This is a piece of diagnostics that might be useful to know how
* often this allocator is being used.
*/
malunal_size_t acquires;
/**
* @brief How many times this allocator was released from.
* @details This is a piece of diagnostics that might be useful to know how
* often this allocator is being used.
*/
malunal_size_t releases;
};
/**
* @brief Executes an initialize request on an allocator.
* @param allocator A pointer to the allocator to initialize.
* @param upstream A pointer to the upstream for the allocator.
* @param capacity The amount of memory to initially reserve.
* @returns An error if the allocator could not be initialized properly;
* otherwise, @c ALLOCATION_ERROR_SUCCESS.
*/
allocation_error_t
allocator_initialize(
allocator_mptr_t allocator,
allocator_mptr_t upstream,
malunal_size_t capacity
);
/**
* @brief Executes a finalize request on an allocator.
* @param allocator A pointer to the allocator to finalize.
* @returns An error if the allocator could not be finalized properly;
* otherwise, @c ALLOCATION_ERROR_SUCCESS.
*/
allocation_error_t
allocator_finalize(
allocator_mptr_t allocator
);
/**
* @brief Executes an acquisition request on an allocator.
* @details This simplifies the execution of an allocator's virtual function
* table entries, specifically @c acquire.
* @param request The acquisition request being made.
* @returns The result of the acquisition request to the allocator.
* @param allocator A pointer to the allocator to use for acquisition.
* @param size The size of the allocation to acquire from the allocator.
* @returns The result of acquisition which indicates if the function threw or
* if the request was fulfilled along with the error or allocation.
*/
allocator_acquire_res_t
allocator_acquire(allocator_acquire_req_t request);
allocation_result_t
allocator_acquire(
allocator_mptr_t allocator,
malunal_size_t size
);
/**
* @brief Executes a reacquisition request on an allocator.
* @details This simplifies the execution of an allocator's virtual function
* table entries, specifically @c reacquire.
* @param request The reacquisition request being made.
* @returns The result of the reacquisition request to the allocator.
* @param allocator A pointer to the allocator to use for reacquisition.
* @param address A pointer to the memory to reacquire from the allocator.
* @param oldsize The size of the old allocation to release.
* @param newsize The size of the new allocation to acquire.
* @returns The result of reacquisition which indicates if the function threw or
* if the request was fulfilled along with the error or allocation.
*/
allocator_acquire_res_t
allocator_reacquire(allocator_reacquire_req_t request);
allocation_result_t
allocator_reacquire(
allocator_mptr_t allocator,
malunal_mptr_t address,
malunal_size_t oldsize,
malunal_size_t newsize
);
/**
* @brief Executes a release request on an allocator.
* @details This simplifies the execution of an allocator's virtual function
* table entries, specifically @c release.
* @param request The release request being made.
* @returns The result of the release request to the allocator.
* @param allocator A pointer to the allocator to use to release the memory.
* @param address A pointer to the memory to release from the allocator.
* @param size The size of the allocation to release.
* @returns An error if the allocator could not release the memory back to the
* allocator; otherwise, @c ALLOCATION_ERROR_SUCCESS.
*/
allocator_exception_t
allocator_release(allocator_release_req_t request);
allocation_error_t
allocator_release(
allocator_mptr_t allocator,
malunal_mptr_t address,
malunal_size_t size
);
/**
* @brief Rounds the given size up to the nearest multiple of @c alignment.
@@ -541,7 +376,7 @@ linux_allocator();
#elif MALUNAL_PLATFORM_WIN32
/**
* @brief Provides a windows specific allocator.
* @details Thisis the windows specific allocator. It uses @c VirtualAlloc and
* @details This is the windows specific allocator. It uses @c VirtualAlloc and
* @c VirtualFree to acquire, reacquire, and release memory.
* @returns An allocator that works specifically with windows.
*/
@@ -549,4 +384,13 @@ allocator_t
win32_allocator();
#endif /* Platform specific allocators */
/**
* @brief Provides an arena allocator.
* @details This will provide appropriate arena allocator functions when the
* instance is created.
* @returns An allocator instance that is populated to be an arena allocator.
*/
allocator_t
arena_allocator();
#endif /* MALUNAL_ALLOCATORS_HEADER */