Expand documentation for custom allocator

Fixes #2298
This commit is contained in:
Camilla Löwy 2024-01-31 01:45:02 +01:00
parent a12311e596
commit 2afd57bf9b
2 changed files with 78 additions and 24 deletions

View File

@ -223,9 +223,9 @@ allocator.user = NULL;
glfwInitAllocator(&allocator); glfwInitAllocator(&allocator);
@endcode @endcode
The allocator will be picked up at the beginning of initialization and will be The allocator will be made active at the beginning of initialization and will be used by
used until GLFW has been fully terminated. Any allocator set after GLFW until the library has been fully terminated. Any allocator set after initialization
initialization will be picked up only at the next 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 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 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 @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. 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 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 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 @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. 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 It receives the memory block to be deallocated and the user pointer passed to @ref
glfwInitAllocator. glfwInitAllocator.
@ -265,6 +271,9 @@ void my_free(void* block, void* user)
} }
@endcode @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 @subsection intro_init_terminate Terminating GLFW

View File

@ -1416,16 +1416,25 @@ typedef struct GLFWcursor GLFWcursor;
* or `NULL` if allocation failed. Note that not all parts of GLFW handle allocation * or `NULL` if allocation failed. Note that not all parts of GLFW handle allocation
* failures gracefully yet. * failures gracefully yet.
* *
* This function may be called during @ref glfwInit but before the library is * 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 * flagged as initialized, as well as during @ref glfwTerminate after the library is no
* library is no longer flagged as initialized. * longer flagged as initialized.
* *
* Any memory allocated by this function will be deallocated during library * Any memory allocated via this function will be deallocated via the same allocator
* termination or earlier. * 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 * The size will always be greater than zero. Allocations of size zero are filtered out
* before reaching the custom allocator. * 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] size The minimum size, in bytes, of the memory block.
* @param[in] user The user-defined pointer from the allocator. * @param[in] user The user-defined pointer from the allocator.
* @return The address of the newly allocated memory block, or `NULL` if an * @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. * @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 init_allocator
* @sa @ref GLFWallocator * @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 * `NULL` if allocation failed. Note that not all parts of GLFW handle allocation
* failures gracefully yet. * failures gracefully yet.
* *
* This function may be called during @ref glfwInit but before the library is * 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 * flagged as initialized, as well as during @ref glfwTerminate after the library is no
* library is no longer flagged as initialized. * longer flagged as initialized.
* *
* Any memory allocated by this function will be deallocated during library * Any memory allocated via this function will be deallocated via the same allocator
* termination or earlier. * 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. * 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 * Reallocations of a block to size zero are converted into deallocations before reaching
* of `NULL` to a non-zero size are converted into regular allocations. * 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] block The address of the memory block to reallocate.
* @param[in] size The new minimum size, in bytes, of the memory block. * @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. * @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 init_allocator
* @sa @ref GLFWallocator * @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 * This function may deallocate the specified memory block. This memory block
* will have been allocated with the same allocator. * will have been allocated with the same allocator.
* *
* This function may be called during @ref glfwInit but before the library is * 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 * flagged as initialized, as well as during @ref glfwTerminate after the library is no
* library is no longer flagged as initialized. * longer flagged as initialized.
* *
* The block address will never be `NULL`. Deallocations of `NULL` are filtered out * The block address will never be `NULL`. Deallocations of `NULL` are filtered out
* before reaching the custom allocator. * 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] block The address of the memory block to deallocate.
* @param[in] user The user-defined pointer from the allocator. * @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. * @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 init_allocator
* @sa @ref GLFWallocator * @sa @ref GLFWallocator
@ -2086,7 +2112,10 @@ typedef struct GLFWgamepadstate
float axes[6]; float axes[6];
} GLFWgamepadstate; } 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 init_allocator
* @sa @ref glfwInitAllocator * @sa @ref glfwInitAllocator
@ -2097,9 +2126,21 @@ typedef struct GLFWgamepadstate
*/ */
typedef struct GLFWallocator typedef struct GLFWallocator
{ {
/*! The memory allocation function. See @ref GLFWallocatefun for details about
* allocation function.
*/
GLFWallocatefun allocate; GLFWallocatefun allocate;
/*! The memory reallocation function. See @ref GLFWreallocatefun for details about
* reallocation function.
*/
GLFWreallocatefun reallocate; GLFWreallocatefun reallocate;
/*! The memory deallocation function. See @ref GLFWdeallocatefun for details about
* deallocation function.
*/
GLFWdeallocatefun deallocate; GLFWdeallocatefun deallocate;
/*! The user pointer for this custom allocator. This value will be passed to the
* allocator functions.
*/
void* user; void* user;
} GLFWallocator; } GLFWallocator;
@ -2232,8 +2273,12 @@ GLFWAPI void glfwInitHint(int hint, int value);
* To use the default allocator, call this function with a `NULL` argument. * 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 * If you specify an allocator struct, every member must be a valid function
* pointer. If any member is `NULL`, this function emits @ref * pointer. If any member is `NULL`, this function will emit @ref
* GLFW_INVALID_VALUE and the init allocator is unchanged. * 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 * @param[in] allocator The allocator to use at the next initialization, or
* `NULL` to use the default one. * `NULL` to use the default one.