287 lines
10 KiB
C
287 lines
10 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/error.h"
|
|
#include "malunal/types/uuid.h"
|
|
|
|
#ifndef MALUNAL_ALLOCATOR_HEADER
|
|
#define MALUNAL_ALLOCATOR_HEADER
|
|
|
|
/**
|
|
* @brief Imports an external constant for the UUID of @c allocator_t.
|
|
* @details This is needed to properly be able to cast @c allocator_t compliant
|
|
* types to an @c allocator_t.
|
|
*/
|
|
extern
|
|
const uuid_t
|
|
UUID_ALLOCATOR_T;
|
|
|
|
/**
|
|
* @brief Imports an external constant for the error domain of @c allocator_t.
|
|
* @details This is needed to detect from what domain an error has come from,
|
|
* so that error codes can mean different things based on its domain.
|
|
*/
|
|
extern
|
|
const error_domain_t
|
|
ERROR_DOMAIN_ALLOCATOR_T;
|
|
|
|
/**
|
|
* @brief A pointer to a function which will attempt to acquire some memory
|
|
* address from the allocator instance, with the size of the buffer
|
|
* equal to @c size and the address placed into the location pointed
|
|
* to by @c out.
|
|
* @param allocator A pointer to the allocator to acquire memory from.
|
|
* @param size The size of the buffer to acquire from the allocator.
|
|
* @param out A pointer to the location where the buffer pointer
|
|
* should be stored if the buffer could be acquired.
|
|
* @returns An error code if the allocator could not acquire the memory.
|
|
*/
|
|
typedef error_t
|
|
(*allocator_acquire_pfn_t)(
|
|
malunal_mptr_t allocator,
|
|
malunal_size_t size,
|
|
malunal_mptr_t* out
|
|
);
|
|
|
|
/**
|
|
* @brief A pointer to a function which will attempt to dispose some memory
|
|
* address back to the allocator instance, given the @c size of the
|
|
* memory buffer at @c address.
|
|
* @param allocator A pointer to the allocator to dispose memory to.
|
|
* @param address A pointer to the memory to dispose to the allocator.
|
|
* @param size The size of the memory buffer to dispose.
|
|
* @returns An error code if the allocator could not dispose the memory.
|
|
*/
|
|
typedef error_t
|
|
(*allocator_dispose_pfn_t)(
|
|
malunal_mptr_t allocator,
|
|
malunal_mptr_t address,
|
|
malunal_size_t size
|
|
);
|
|
|
|
/**
|
|
* @brief Defines the allocator virtual function table.
|
|
* @details Implementing classes of the allocator interface are expected to
|
|
* provide valid pointers to these functions that are implementation
|
|
* specific.
|
|
*/
|
|
typedef struct {
|
|
/**
|
|
* @brief A pointer to a function which will attempt to acquire some memory
|
|
* address from the allocator instance, with the size of the buffer
|
|
* equal to @c size and the address placed into the location pointed
|
|
* to by @c out.
|
|
*/
|
|
allocator_acquire_pfn_t const acquire;
|
|
|
|
/**
|
|
* @brief A pointer to a function which will attempt to dispose some memory
|
|
* address back to the allocator instance, given the @c size of the
|
|
* memory buffer at @c address.
|
|
*/
|
|
allocator_dispose_pfn_t const dispose;
|
|
} allocator_vtable_t;
|
|
|
|
|
|
/**
|
|
* @brief Defines the abstract allocator object.
|
|
* @details Since this is only an interface, it only contains a pointer to the
|
|
* virtual table for itself. Other objects which implement this, may
|
|
* come with member variables.
|
|
*/
|
|
typedef struct {
|
|
/**
|
|
* @brief A pointer to an immutable allocator virtual function table.
|
|
* @details Contains the function pointers to the allocator specific functions
|
|
* that make this allocator function as one.
|
|
*/
|
|
const allocator_vtable_t* vtable;
|
|
} 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 errors 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 The generic allocator error.
|
|
* @details If the allocator does not know what to throw, or in test cases,
|
|
* this may be thrown.
|
|
*/
|
|
ALLOCATOR_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.
|
|
*/
|
|
ALLOCATOR_ERROR_NULL_ALLOCATOR,
|
|
|
|
/**
|
|
* @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_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.
|
|
*/
|
|
ALLOCATOR_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 error.
|
|
*/
|
|
ALLOCATOR_ERROR_LEAKY_MEMORY,
|
|
} allocator_error_t;
|
|
|
|
|
|
/**
|
|
* @brief Attempts to acquire some memory buffer from the provided allocator.
|
|
* @details This will perform some checks before trying to call the virtual
|
|
* function table implementation provided by the allocator. If all
|
|
* pre-conditions pass, then the virtual function will be called and
|
|
* its result passed back to the caller.
|
|
* @param allocator A pointer to the allocator to call @c acquire on.
|
|
* @param size The size of the memory buffer to acquire.
|
|
* @param out The location where to store the acquired buffer.
|
|
* @returns An error if the allocator could not acquire a memory buffer for the
|
|
* function caller.
|
|
*/
|
|
error_t
|
|
allocator_acquire(
|
|
allocator_mptr_t allocator,
|
|
malunal_size_t size,
|
|
malunal_mptr_t* out
|
|
);
|
|
|
|
/**
|
|
* @brief Attempts to dispose some memory buffer into the provided allocator.
|
|
* @details This will perform some checks before trying to call the virtual
|
|
* function table implementation provided by the allocator. If all
|
|
* pre-conditions pass, then the virtual function will be called and
|
|
* its result passed back to the caller.
|
|
* @param allocator A pointer to the allocator to call @c dispose on.
|
|
* @param address A poitner to the memory buffer to dispose.
|
|
* @param size The size of the memory buffer to dispose.
|
|
* @returns An error if the allocator could not dispose a memory buffer for the
|
|
* function caller.
|
|
*/
|
|
error_t
|
|
allocator_dispose(
|
|
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_mptr_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_mptr_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_mptr_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_mptr_t
|
|
win32_allocator();
|
|
#endif /* Platform specific allocators */
|
|
|
|
#endif /* MALUNAL_ALLOCATOR_HEADER */
|