From 2afd57bf9b371f30bf654d9fefff6bd39b981933 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilla=20L=C3=B6wy?= Date: Wed, 31 Jan 2024 01:45:02 +0100 Subject: [PATCH] Expand documentation for custom allocator Fixes #2298 --- docs/intro.dox | 15 ++++++-- include/GLFW/glfw3.h | 87 +++++++++++++++++++++++++++++++++----------- 2 files changed, 78 insertions(+), 24 deletions(-) diff --git a/docs/intro.dox b/docs/intro.dox index 36ec0ef5..bfb3ddcd 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -223,9 +223,9 @@ allocator.user = NULL; glfwInitAllocator(&allocator); @endcode -The allocator will be picked up at the beginning of initialization and will be -used until GLFW has been fully terminated. Any allocator set after -initialization will be picked up only at the next initialization. +The allocator will be made active at the beginning of initialization and will be used by +GLFW until the library has been fully terminated. Any allocator set after initialization +will be picked up only at the next initialization. The allocator will only be used for allocations that would have been made with the C standard library. Memory allocations that must be made with platform @@ -242,6 +242,9 @@ void* my_malloc(size_t size, void* user) } @endcode +The documentation for @ref GLFWallocatefun also lists the requirements and limitations for +an allocation function. If the active one does not meet all of these, GLFW may fail. + The reallocation function must have a function signature matching @ref GLFWreallocatefun. It receives the memory block to be reallocated, the new desired size, in bytes, and the user pointer passed to @ref glfwInitAllocator and returns the address to the resized memory @@ -254,6 +257,9 @@ void* my_realloc(void* block, size_t size, void* user) } @endcode +The documentation for @ref GLFWreallocatefun also lists the requirements and limitations +for a reallocation function. If the active one does not meet all of these, GLFW may fail. + The deallocation function must have a function signature matching @ref GLFWdeallocatefun. It receives the memory block to be deallocated and the user pointer passed to @ref glfwInitAllocator. @@ -265,6 +271,9 @@ void my_free(void* block, void* user) } @endcode +The documentation for @ref GLFWdeallocatefun also lists the requirements and limitations +for a deallocation function. If the active one does not meet all of these, GLFW may fail. + @subsection intro_init_terminate Terminating GLFW diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index f86b176c..aafd1621 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -1416,16 +1416,25 @@ typedef struct GLFWcursor GLFWcursor; * or `NULL` if allocation failed. Note that not all parts of GLFW handle allocation * failures gracefully yet. * - * This function may be called during @ref glfwInit but before the library is - * flagged as initialized, as well as during @ref glfwTerminate after the - * library is no longer flagged as initialized. + * This function must support being called during @ref glfwInit but before the library is + * flagged as initialized, as well as during @ref glfwTerminate after the library is no + * longer flagged as initialized. * - * Any memory allocated by this function will be deallocated during library - * termination or earlier. + * Any memory allocated via this function will be deallocated via the same allocator + * during library termination or earlier. + * + * Any memory allocated via this function must be suitably aligned for any object type. + * If you are using C99 or earlier, this alignment is platform-dependent but will be the + * same as what `malloc` provides. If you are using C11 or later, this is the value of + * `alignof(max_align_t)`. * * The size will always be greater than zero. Allocations of size zero are filtered out * before reaching the custom allocator. * + * If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY. + * + * This function must not call any GLFW function. + * * @param[in] size The minimum size, in bytes, of the memory block. * @param[in] user The user-defined pointer from the allocator. * @return The address of the newly allocated memory block, or `NULL` if an @@ -1436,7 +1445,8 @@ typedef struct GLFWcursor GLFWcursor; * * @reentrancy This function should not call any GLFW function. * - * @thread_safety This function may be called from any thread that calls GLFW functions. + * @thread_safety This function must support being called from any thread that calls GLFW + * functions. * * @sa @ref init_allocator * @sa @ref GLFWallocator @@ -1459,16 +1469,26 @@ typedef void* (* GLFWallocatefun)(size_t size, void* user); * `NULL` if allocation failed. Note that not all parts of GLFW handle allocation * failures gracefully yet. * - * This function may be called during @ref glfwInit but before the library is - * flagged as initialized, as well as during @ref glfwTerminate after the - * library is no longer flagged as initialized. + * This function must support being called during @ref glfwInit but before the library is + * flagged as initialized, as well as during @ref glfwTerminate after the library is no + * longer flagged as initialized. * - * Any memory allocated by this function will be deallocated during library - * termination or earlier. + * Any memory allocated via this function will be deallocated via the same allocator + * during library termination or earlier. + * + * Any memory allocated via this function must be suitably aligned for any object type. + * If you are using C99 or earlier, this alignment is platform-dependent but will be the + * same as what `realloc` provides. If you are using C11 or later, this is the value of + * `alignof(max_align_t)`. * * The block address will never be `NULL` and the size will always be greater than zero. - * Reallocations of a block to size zero are converted into deallocations. Reallocations - * of `NULL` to a non-zero size are converted into regular allocations. + * Reallocations of a block to size zero are converted into deallocations before reaching + * the custom allocator. Reallocations of `NULL` to a non-zero size are converted into + * regular allocations before reaching the custom allocator. + * + * If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY. + * + * This function must not call any GLFW function. * * @param[in] block The address of the memory block to reallocate. * @param[in] size The new minimum size, in bytes, of the memory block. @@ -1481,7 +1501,8 @@ typedef void* (* GLFWallocatefun)(size_t size, void* user); * * @reentrancy This function should not call any GLFW function. * - * @thread_safety This function may be called from any thread that calls GLFW functions. + * @thread_safety This function must support being called from any thread that calls GLFW + * functions. * * @sa @ref init_allocator * @sa @ref GLFWallocator @@ -1503,13 +1524,17 @@ typedef void* (* GLFWreallocatefun)(void* block, size_t size, void* user); * This function may deallocate the specified memory block. This memory block * will have been allocated with the same allocator. * - * This function may be called during @ref glfwInit but before the library is - * flagged as initialized, as well as during @ref glfwTerminate after the - * library is no longer flagged as initialized. + * This function must support being called during @ref glfwInit but before the library is + * flagged as initialized, as well as during @ref glfwTerminate after the library is no + * longer flagged as initialized. * * The block address will never be `NULL`. Deallocations of `NULL` are filtered out * before reaching the custom allocator. * + * If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY. + * + * This function must not call any GLFW function. + * * @param[in] block The address of the memory block to deallocate. * @param[in] user The user-defined pointer from the allocator. * @@ -1518,7 +1543,8 @@ typedef void* (* GLFWreallocatefun)(void* block, size_t size, void* user); * * @reentrancy This function should not call any GLFW function. * - * @thread_safety This function may be called from any thread that calls GLFW functions. + * @thread_safety This function must support being called from any thread that calls GLFW + * functions. * * @sa @ref init_allocator * @sa @ref GLFWallocator @@ -2086,7 +2112,10 @@ typedef struct GLFWgamepadstate float axes[6]; } GLFWgamepadstate; -/*! @brief +/*! @brief Custom heap memory allocator. + * + * This describes a custom heap memory allocator for GLFW. To set an allocator, pass it + * to @ref glfwInitAllocator before initializing the library. * * @sa @ref init_allocator * @sa @ref glfwInitAllocator @@ -2097,9 +2126,21 @@ typedef struct GLFWgamepadstate */ typedef struct GLFWallocator { + /*! The memory allocation function. See @ref GLFWallocatefun for details about + * allocation function. + */ GLFWallocatefun allocate; + /*! The memory reallocation function. See @ref GLFWreallocatefun for details about + * reallocation function. + */ GLFWreallocatefun reallocate; + /*! The memory deallocation function. See @ref GLFWdeallocatefun for details about + * deallocation function. + */ GLFWdeallocatefun deallocate; + /*! The user pointer for this custom allocator. This value will be passed to the + * allocator functions. + */ void* user; } GLFWallocator; @@ -2232,8 +2273,12 @@ GLFWAPI void glfwInitHint(int hint, int value); * To use the default allocator, call this function with a `NULL` argument. * * If you specify an allocator struct, every member must be a valid function - * pointer. If any member is `NULL`, this function emits @ref - * GLFW_INVALID_VALUE and the init allocator is unchanged. + * pointer. If any member is `NULL`, this function will emit @ref + * GLFW_INVALID_VALUE and the init allocator will be unchanged. + * + * The functions in the allocator must fulfil a number of requirements. See the + * documentation for @ref GLFWallocatefun, @ref GLFWreallocatefun and @ref + * GLFWdeallocatefun for details. * * @param[in] allocator The allocator to use at the next initialization, or * `NULL` to use the default one.