397 lines
14 KiB
C
397 lines
14 KiB
C
/**
|
|
* @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)
|
|
|
|
|
|
// 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 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 {
|
|
malunal_uint8_t __opaque[ALLOCATOR_SIZE];
|
|
} 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 {
|
|
/**
|
|
* @brief No exception was thrown.
|
|
* @details Some allocator functions only return an exception. This indicates
|
|
* for those functions that the operation was successful.
|
|
*/
|
|
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.
|
|
*/
|
|
ALLOCATION_ERROR_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.
|
|
*/
|
|
ALLOCATION_ERROR_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.
|
|
*/
|
|
ALLOCATION_ERROR_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.
|
|
*/
|
|
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.
|
|
*/
|
|
ALLOCATION_ERROR_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.
|
|
*/
|
|
ALLOCATION_ERROR_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.
|
|
*/
|
|
ALLOCATION_ERROR_LEAKY_MEMORY,
|
|
} allocation_error_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 {
|
|
/**
|
|
* @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;
|
|
|
|
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.
|
|
*/
|
|
allocation_error_t error;
|
|
};
|
|
} allocation_result_t;
|
|
|
|
/**
|
|
* @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.
|
|
*/
|
|
allocation_error_t
|
|
allocator_upstream(
|
|
allocator_mptr_t allocator,
|
|
allocator_mptr_t* out
|
|
);
|
|
|
|
/**
|
|
* @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.
|
|
*/
|
|
allocation_error_t
|
|
allocator_allocated_bytes(
|
|
allocator_mptr_t allocator,
|
|
malunal_size_t* out
|
|
);
|
|
|
|
/**
|
|
* @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.
|
|
*/
|
|
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 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.
|
|
*/
|
|
allocation_error_t
|
|
allocator_releases_count(
|
|
allocator_mptr_t allocator,
|
|
malunal_size_t* out
|
|
);
|
|
|
|
/**
|
|
* @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.
|
|
* @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.
|
|
*/
|
|
allocation_result_t
|
|
allocator_acquire(
|
|
allocator_mptr_t allocator,
|
|
malunal_size_t size
|
|
);
|
|
|
|
/**
|
|
* @brief Executes a reacquisition request on an 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.
|
|
*/
|
|
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.
|
|
* @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.
|
|
*/
|
|
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.
|
|
* @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 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.
|
|
*/
|
|
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 */
|