From f8749ba238c9e0e938984006ab04455f8a06b308 Mon Sep 17 00:00:00 2001 From: Eric-Paul Ickhorn Date: Thu, 23 May 2024 00:52:48 +0200 Subject: [PATCH] documentation(arena): Added comments to the functions and the arena-structure. --- inc-c/ufn/ufn_arena.h | 38 ++++++++++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/inc-c/ufn/ufn_arena.h b/inc-c/ufn/ufn_arena.h index de3937e..d90a287 100644 --- a/inc-c/ufn/ufn_arena.h +++ b/inc-c/ufn/ufn_arena.h @@ -1,4 +1,5 @@ -// UFN Arena library. MIT-Licensed (c) Eric-Paul Ickhorn (epickh) +// ufn_arena.h: An arena allocator with maximum usage limiter. +// Under MIT-License. Copyright by Eric-Paul Ickhorn (epickh). #ifndef UFN_ARENA_H #define UFN_ARENA_H @@ -9,6 +10,8 @@ typedef struct ufn_arena ufn_arena_s; +/// @brief Arena structure which is being acted upon by the arena +/// functions. Manual modification may lead to undesired behaviour. struct ufn_arena { uint32_t capacity; @@ -19,16 +22,42 @@ struct ufn_arena ufn_arena_s *continuation; }; +/// @brief Allocates a new arena tree with up to 'max_tree_size' . +/// @warning No later but possibly earlier than when a total of +/// 'max_tree_size' was distributed, the allocation function +/// (ufn_arena_alloc) will return NULL. +/// @param capacity Number of bytes to allocate in the first arena; +/// Determines how many bytes can be distributed. +/// @param max_tree_size Maximum number of bytes to allocate for the +/// continuations. If this is less than or equal to +/// 'capacity' * 2, the next continuation will be +/// the last one. +/// @return Newly created dynamic arena. ufn_arena_s * ufn_new_dynamic_arena(uint32_t capacity, uint32_t max_tree_size); + +/// @brief Allocates a new arena with an immutable capacity. +/// @warning If this arena's allocation is full, +/// 'ufn_arena_alloc' will return NULL! +/// @note Internally calls 'ufn_new_dynamic_arena' with a maximum tree size of 0. +/// @param capacity Number of bytes to allocate in the arena; +/// Determines how many bytes can be distributed. +/// @return Newly created arena. ufn_arena_s * ufn_new_static_arena(uint32_t capacity); + +/// @brief Frees an arena and all its dynamic continuations. +/// @param arena Arena to free. void ufn_free_arena(ufn_arena_s *arena); +/// @brief Allocates a block of size 'size' in the arena 'arena' +/// @warning Will return NULL if no memory block of length 'size' +/// is available in the arena or any of the continuations. +/// @param arena Arena to use for allocating 'size' bytes. +/// @param size Number of bytes to allocate. +/// @return Pointer to the newly allocated block. void * ufn_arena_alloc(ufn_arena_s *arena, uint32_t size); - - +// END OF API, START OF IMPLEMENTATION. #ifdef UFN_IMPLEMENTATION - #include ufn_arena_s * ufn_new_dynamic_arena(uint32_t capacity, uint32_t max_tree_size) @@ -93,4 +122,5 @@ void * ufn_arena_alloc(ufn_arena_s *arena, uint32_t size) #endif // UFN_IMPLEMENTATION + #endif // UFN_ARENA_H