Initial commit
This commit is contained in:
@@ -0,0 +1,552 @@
|
||||
/**
|
||||
* @file allocators.h
|
||||
* @brief This header contains the definition of the memory functions and basic
|
||||
* allocator object.
|
||||
* @author John Christman (sorakatadzuma@gmail.com)
|
||||
* @copyright Malunal Studios, LLC.
|
||||
*/
|
||||
#include "malunal/config.h"
|
||||
#include "malunal/types.h"
|
||||
|
||||
#ifndef MALUNAL_ALLOCATORS_HEADER
|
||||
#define MALUNAL_ALLOCATORS_HEADER
|
||||
|
||||
// Assuring that NULL_ADDRESS is correct.
|
||||
#ifdef NULL_ADDRESS
|
||||
#undef NULL_ADDRESS
|
||||
#endif /* NULL_ADDRESS */
|
||||
|
||||
/**
|
||||
* @def NULL_ADDRESS
|
||||
* @brief Defines a null address.
|
||||
* @details This is needed for functions to indicate that an address could not
|
||||
* acquired.
|
||||
*/
|
||||
#define NULL_ADDRESS ((void*)0)
|
||||
|
||||
/**
|
||||
* @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.
|
||||
*/
|
||||
typedef struct Allocator allocator_t;
|
||||
|
||||
/**
|
||||
* @brief A pointer to a mutable allocator.
|
||||
* @details This is provided to simplify type declarations for functions
|
||||
* requiring allocators that are meant to be mutable.
|
||||
*/
|
||||
typedef allocator_t* allocator_mptr_t;
|
||||
|
||||
/**
|
||||
* @brief A pointer to a immutable allocator view.
|
||||
* @details This is provided to simplify type declarations for functions
|
||||
* requiring allocators that are meant to be immutable.
|
||||
*/
|
||||
typedef const allocator_t* allocator_iptr_t;
|
||||
|
||||
|
||||
/**
|
||||
* @brief Defines a set of exception that an allocator may throw.
|
||||
* @details These are extremely useful for debugging an allocator or catching
|
||||
* runtime issues that can be fixed.
|
||||
*/
|
||||
typedef enum AllocatorException {
|
||||
/**
|
||||
* @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,
|
||||
|
||||
/**
|
||||
* @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,
|
||||
|
||||
/**
|
||||
* @brief The allocator instance was null.
|
||||
* @details Allocator functions take it by reference because it is a rather
|
||||
* large object. So, when the reference is expected to be non-null,
|
||||
* which is always, this will be thrown.
|
||||
*/
|
||||
ALLOCATOR_EXCEPTION_NULL_ALLOCATOR,
|
||||
|
||||
/**
|
||||
* @brief The allocator upstream was null.
|
||||
* @details Allocator implementations may expect for the upstream parameter
|
||||
* 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,
|
||||
|
||||
/**
|
||||
* @brief The allocator context was null.
|
||||
* @details Allocator implementations often expect for the context parameter
|
||||
* 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,
|
||||
|
||||
/**
|
||||
* @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,
|
||||
|
||||
/**
|
||||
* @brief The address being released does not belong to the allocator.
|
||||
* @details Allocators expect any given address to have been allocated by
|
||||
* 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,
|
||||
|
||||
/**
|
||||
* @brief The allocator has determined that memory is being leaked.
|
||||
* @details Given the diagnostics within an allocator, the allocator may find
|
||||
* 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;
|
||||
|
||||
/**
|
||||
* @brief Represents the result of an acquisition request.
|
||||
* @details This has two parts to it: a fulfilled acquisition and an possible
|
||||
* exception. Which part is put into the result is indicated by the
|
||||
* @c threw tag.
|
||||
*/
|
||||
typedef struct AllocatorAcquireResult {
|
||||
/**
|
||||
* @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.
|
||||
*/
|
||||
malunal_bool_t threw;
|
||||
|
||||
union {
|
||||
/**
|
||||
* @brief The success of fulfilling the acquisition request.
|
||||
* @details If the allocator sucessfully fulfilled the request, this will
|
||||
* contain the pointer of the allocation.
|
||||
*/
|
||||
malunal_mptr_t address;
|
||||
|
||||
/**
|
||||
* @brief The failure of fulfilling the acquisition request.
|
||||
* @details If the allocator unsuccessfully fulfilled the request, this will
|
||||
* contain the reason for failure.
|
||||
*/
|
||||
allocator_exception_t exception;
|
||||
};
|
||||
} allocator_acquire_res_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.
|
||||
*/
|
||||
typedef allocator_acquire_res_t
|
||||
(*allocator_acquire_pfn_t)(
|
||||
allocator_acquire_req_t request
|
||||
);
|
||||
|
||||
|
||||
/**
|
||||
* @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.
|
||||
*/
|
||||
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
|
||||
);
|
||||
|
||||
|
||||
/**
|
||||
* @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.
|
||||
*/
|
||||
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
|
||||
);
|
||||
|
||||
|
||||
/**
|
||||
* @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.
|
||||
*/
|
||||
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;
|
||||
|
||||
/**
|
||||
* @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 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.
|
||||
*/
|
||||
allocator_acquire_res_t
|
||||
allocator_acquire(allocator_acquire_req_t request);
|
||||
|
||||
/**
|
||||
* @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.
|
||||
*/
|
||||
allocator_acquire_res_t
|
||||
allocator_reacquire(allocator_reacquire_req_t request);
|
||||
|
||||
/**
|
||||
* @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.
|
||||
*/
|
||||
allocator_exception_t
|
||||
allocator_release(allocator_release_req_t request);
|
||||
|
||||
/**
|
||||
* @brief Rounds the given size up to the nearest multiple of @c alignment.
|
||||
* @param size The current size to round up to the nearest multiple of
|
||||
* the provided @c alignment.
|
||||
* @param alignment The alignment to round the size to.
|
||||
* @returns The rounded size.
|
||||
*/
|
||||
malunal_size_t
|
||||
align_to(
|
||||
malunal_size_t size,
|
||||
malunal_size_t alignment
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Rounds the given size up to the nearest page.
|
||||
* @details This will give you a size that is rounded up to the next multiple of
|
||||
* the platform page size. For example, if you provide 4000 and the
|
||||
* platform page size is 4096, then you will get 4096. Likewise, if you
|
||||
* provided 5000 and the platform page size is 4096, then you will get
|
||||
* 8192.
|
||||
* @param size The current size that will be rounded up to the nearest page
|
||||
* multiple for the platform.
|
||||
* @returns The rounded page size.
|
||||
*/
|
||||
malunal_size_t
|
||||
align_to_page(malunal_size_t size);
|
||||
|
||||
/**
|
||||
* @brief Provides the platform page size.
|
||||
* @details This can be really useful when you plan to allocate a lot of memory.
|
||||
* Platforms typically round memory requests up to the nearest page and
|
||||
* give the base address of the virtually allocated block back, but
|
||||
* placing a guard on the portion of the memory that will not be used.
|
||||
* By querying the page size for the platform and rounding a memory
|
||||
* acquisition request up to the nearest page, you can get the full
|
||||
* block the platform intends to hand back which, significantly helps
|
||||
* in proper memory tracking.
|
||||
* @returns The memory page size for the platform.
|
||||
*/
|
||||
malunal_size_t
|
||||
platform_page_size();
|
||||
|
||||
/**
|
||||
* @brief Provides the general libc allocator.
|
||||
* @details This will provide a general purpose allocator backed by the standard
|
||||
* library. The functions provided are equivalent to @c malloc,
|
||||
* @c realloc, and @c free.
|
||||
* @returns An allocator that interfaces with libc.
|
||||
*/
|
||||
allocator_t
|
||||
libc_allocator();
|
||||
|
||||
/**
|
||||
* @brief Provides the platform allocator.
|
||||
* @details This will provide the appropriate platform allocator depending on
|
||||
* what operating system this library was compiled for.
|
||||
* @returns One of: @c linux_allocator or @c win32_allocator.
|
||||
*/
|
||||
allocator_t
|
||||
platform_allocator();
|
||||
|
||||
#if MALUNAL_PLATFORM_LINUX
|
||||
/**
|
||||
* @brief Provides a linux specific allocator.
|
||||
* @details This is the linux specific allocator. It uses @c mmap and @c munmap
|
||||
* to acquire, reacquire, and release memory.
|
||||
* @returns An allocator that works specifically with linux.
|
||||
*/
|
||||
allocator_t
|
||||
linux_allocator();
|
||||
#elif MALUNAL_PLATFORM_WIN32
|
||||
/**
|
||||
* @brief Provides a windows specific allocator.
|
||||
* @details Thisis 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.
|
||||
*/
|
||||
allocator_t
|
||||
win32_allocator();
|
||||
#endif /* Platform specific allocators */
|
||||
|
||||
#endif /* MALUNAL_ALLOCATORS_HEADER */
|
||||
Reference in New Issue
Block a user