documentation(arena): Added comments to the functions and the arena-structure.

This commit is contained in:
Eric-Paul Ickhorn 2024-05-23 00:52:48 +02:00
parent 7ebd70c59c
commit f8749ba238
1 changed files with 34 additions and 4 deletions

View File

@ -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 <stdlib.h>
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