|
memory_arena
|
Base group for internal implementation details. More...
Collaboration diagram for Internal Implementation:Modules | |
| Arena Initialization Internals | |
| Internal helpers for arena setup and configuration. | |
| Arena Cleanup Internals | |
| Internal helpers for teardown and memory release. | |
| Arena Allocation Internals | |
| Internal helpers for memory allocation logic. | |
| Sub-Arena Internals | |
| Internal helpers for configuring sub-arenas. | |
| Arena Resize Internals | |
| Internal helpers for growing and shrinking memory buffers. | |
| Scratch Arena Internals | |
| Internal helpers and utilities for scratch arena pool management. | |
Files | |
| file | arena_internal.c |
| Internal utilities and metadata management for the Arena memory system. | |
| file | arena_internal.h |
| Internal utilities and helpers for arena memory management. | |
Functions | |
| static size_t | align_up (size_t value, size_t alignment) |
Align a value upwards to the nearest multiple of alignment. | |
| static void * | arena_alloc_buffer (size_t size) |
| Allocate a zero-initialized memory buffer for the arena. | |
| static t_arena * | arena_alloc_struct (void) |
| Allocate and zero-initialize a new arena struct. | |
| static bool | arena_finish_init (t_arena *arena, void *buffer, size_t size, bool allow_grow) |
| Finalize the initialization of an arena with a provided buffer. | |
| static bool | arena_init_mutex (t_arena *arena) |
| Initialize the mutex used for thread-safe arena operations. | |
| bool | arena_is_valid (const t_arena *arena) |
| Check whether the given arena is in a valid, initialized state. | |
| static void | arena_log_and_teardown (t_arena **arena, const char *msg) |
| Report an error, destroy the arena, and free its memory. | |
| static void | arena_reset_metadata (t_arena *arena) |
| Reset all arena metadata fields to their default initial state. | |
| static bool | arena_set_allocated_buffer (t_arena *arena, size_t size) |
| Allocate and assign a zero-initialized buffer to an arena. | |
| static void | arena_set_default_label (t_arena *arena, const char *fallback) |
| Set a fallback debug label if none is set. | |
| static bool | arena_set_or_alloc_buffer (t_arena *arena, void *buffer, size_t size) |
| Configure an arena's buffer by either assigning a user-provided region or allocating one internally. | |
| static void | arena_set_user_buffer (t_arena *arena, void *buffer, size_t size) |
| Assign a user-provided buffer to an arena without taking ownership. | |
| void | arena_update_peak (t_arena *arena) |
| Update the arena’s peak memory usage if the current usage exceeds it. | |
| void | arena_zero_metadata (t_arena *arena) |
| Zero out and reset all debug/stats metadata associated with the arena. | |
| size_t | default_grow_cb (size_t current_size, size_t requested_size) |
| Default growth policy callback for arena resizing. | |
| static size_t | next_power_of_two (size_t x) |
Return the next power of two greater than or equal to x. | |
| static bool | would_overflow_mul (size_t a, size_t b, size_t *result) |
Perform a checked multiplication of two size_t values. | |
Base group for internal implementation details.
This group collects all static inline functions, helpers, and low-level logic used internally by the arena system. These are not part of the public API and may change at any time.
|
inlinestatic |
#include <arena_math.h>
Align a value upwards to the nearest multiple of alignment.
Returns the smallest multiple of alignment that is greater than or equal to value. alignment must be a power of two.
| value | The value to align. |
| alignment | The alignment boundary (must be power of two). |
Definition at line 52 of file arena_math.h.
|
inlinestatic |
#include <arena_create.c>
Allocate a zero-initialized memory buffer for the arena.
This function wraps calloc to allocate a contiguous zeroed memory region of size bytes. It is used when the arena needs to allocate its own internal memory buffer (rather than relying on an external one provided by the user).
If allocation fails, the function reports the failure using arena_report_error.
| size | The number of bytes to allocate. |
NULL if allocation fails.Definition at line 492 of file arena_create.c.
References arena_report_error().
|
inlinestatic |
#include <arena_create.c>
Allocate and zero-initialize a new arena struct.
This internal helper allocates memory for a t_arena structure using calloc, which ensures all fields are zero-initialized. This guarantees a clean slate before any initialization logic is applied, helping avoid undefined behavior from stale data.
On failure, the function returns NULL. The calling function is responsible for handling the failure and cleaning up if needed.
This function does not allocate the memory buffer used for allocations— it only handles the control structure itself.
t_arena, or NULL on failure.Definition at line 426 of file arena_create.c.
|
inlinestatic |
#include <arena_create.c>
Finalize the initialization of an arena with a provided buffer.
This internal helper is used to complete the setup of an arena after a memory buffer has been successfully allocated.
The function performs the following:
arena_reset_metadata.If mutex initialization fails, the buffer is freed immediately to avoid memory leaks and the function returns false. Ownership of the arena structure itself remains with the caller.
| arena | Pointer to the arena being initialized. |
| buffer | Pre-allocated memory buffer for arena use. |
| size | Size of the memory buffer in bytes. |
| allow_grow | Whether the arena may grow dynamically if full. |
true on success, false if mutex setup failed.Definition at line 640 of file arena_create.c.
References arena_generate_id(), arena_init_mutex(), and arena_reset_metadata().
|
inlinestatic |
#include <arena_create.c>
Initialize the mutex used for thread-safe arena operations.
If ARENA_ENABLE_THREAD_SAFE is defined, this function sets up a recursive pthread_mutex_t for the arena, enabling safe concurrent access to mutable fields like offset or marker stack state.
It uses PTHREAD_MUTEX_RECURSIVE to allow nested locks within the same thread, which is necessary for safe usage patterns like reentrant allocators or hooks.
On failure during any part of mutex attribute or lock initialization, it logs a detailed error and returns false. The caller is expected to clean up on failure.
If thread safety is not enabled at compile time, the function is a no-op that always returns true.
| arena | Pointer to the arena for which the mutex should be initialized. |
true on success, false if mutex setup failed.Definition at line 585 of file arena_create.c.
References arena_report_error().
| bool arena_is_valid | ( | const t_arena * | arena | ) |
#include <arena_internal.h>
Check whether the given arena is in a valid, initialized state.
Check whether an arena is in a valid state.
| arena | Pointer to the arena to check. |
true if the arena is valid, false otherwise.This function verifies the structural integrity of a t_arena instance. It ensures:
NULL.This is useful for defensive checks before performing operations on an arena.
| arena | Pointer to the arena to validate. |
true if the arena is valid, false otherwise.Definition at line 150 of file arena_internal.c.
|
inlinestatic |
#include <arena_create.c>
Report an error, destroy the arena, and free its memory.
This helper is used to cleanly handle failure paths in arena creation or initialization. It prints a formatted error message using arena_report_error, then proceeds to safely destroy the arena and free the t_arena structure via arena_destroy() and arena_delete().
If the arena pointer is NULL or points to NULL, only the error is logged and no cleanup is performed. This guards against double-frees or null dereferences.
| arena | A pointer to a pointer to a t_arena structure. May be NULL. |
| msg | A formatted error message passed to arena_report_error. |
arena and will leave the pointer invalid.Definition at line 458 of file arena_create.c.
References arena_delete(), arena_destroy(), and arena_report_error().
|
inlinestatic |
#include <arena_create.c>
Reset all arena metadata fields to their default initial state.
This function clears the entire t_arena structure's internal metadata, ensuring a clean and consistent base before the arena is initialized.
It performs the following actions:
arena_stats_reset.owns_buffer, can_grow, and is_destroying.This function must be called before using or reinitializing the arena. It is designed to avoid stale data and ensure safe concurrent visibility.
| arena | Pointer to the arena to reset. |
Definition at line 530 of file arena_create.c.
References arena_default_error_callback(), arena_stats_reset(), and default_grow_cb().
|
inlinestatic |
#include <arena_create.c>
Allocate and assign a zero-initialized buffer to an arena.
This function is used internally when no user-supplied buffer is provided during arena_init_with_buffer. It dynamically allocates a memory region of the requested size using calloc, stores the resulting buffer and size into the arena, and marks the arena as the owner of the buffer so it can be freed on destruction.
If the memory allocation fails, the function logs a formatted error using arena_report_error and returns false.
| arena | Pointer to the arena receiving the allocated buffer. |
| size | Number of bytes to allocate. |
true if allocation and assignment succeeded, false on failure.Definition at line 682 of file arena_create.c.
References arena_report_error().
|
inlinestatic |
#include <arena_create.c>
Set a fallback debug label if none is set.
This internal utility ensures that an arena has a human-readable label for debugging and error reporting. If the arena->debug.label is NULL, it assigns the provided fallback label.
Labels are used in logs and diagnostic tools to identify arenas more easily, especially in multi-arena systems or when visualizing memory usage.
This function is used during initialization, after clearing metadata.
| arena | Pointer to the arena structure to label. |
| fallback | The default label to assign if no label is already set. |
Definition at line 398 of file arena_create.c.
|
inlinestatic |
#include <arena_create.c>
Configure an arena's buffer by either assigning a user-provided region or allocating one internally.
This helper determines whether to allocate memory or use an existing buffer based on the parameters:
buffer is NULL and size > 0, it allocates a new zeroed buffer using calloc.In both cases, it updates the owns_buffer flag accordingly to ensure proper cleanup behavior in arena_destroy(). This function helps unify buffer configuration logic in arena_init_with_buffer, reducing duplication and clarifying intent.
| arena | Pointer to the arena to configure. |
| buffer | Pointer to the caller-supplied memory buffer (can be NULL). |
| size | Size (in bytes) of the buffer. |
true on success, false if memory allocation failed.Definition at line 750 of file arena_create.c.
References arena_set_allocated_buffer(), and arena_set_user_buffer().
|
inlinestatic |
#include <arena_create.c>
Assign a user-provided buffer to an arena without taking ownership.
This function sets up the arena's buffer and size fields using a buffer provided by the caller. It does not allocate or copy memory — it simply stores the pointer and size, and marks the arena as not owning the buffer. This means the buffer will not be freed when the arena is destroyed.
It is typically used when initializing or reinitializing an arena that operates over pre-allocated memory regions, such as stack memory or memory-mapped regions.
| arena | Pointer to the arena being configured. |
| buffer | Pointer to the caller-supplied buffer. |
| size | Size (in bytes) of the buffer. |
Definition at line 719 of file arena_create.c.
| void arena_update_peak | ( | t_arena * | arena | ) |
#include <arena_internal.h>
Update the arena’s peak memory usage if the current usage exceeds it.
Update the peak usage metric of the arena.
| arena | Pointer to the arena to update. |
This internal function updates the peak_usage statistic in the arena if the current offset exceeds the previously recorded peak. This metric reflects the highest memory usage observed since the arena was initialized or last reset.
It uses locking to ensure thread-safe updates in concurrent environments.
| arena | Pointer to the arena whose peak usage should be updated. |
Definition at line 118 of file arena_internal.c.
References ARENA_LOCK, and ARENA_UNLOCK.
| void arena_zero_metadata | ( | t_arena * | arena | ) |
#include <arena_internal.h>
Zero out and reset all debug/stats metadata associated with the arena.
Reset all metadata fields in an arena to their default values.
| arena | Pointer to the arena to zero. |
This function clears all metadata inside a t_arena structure, preparing it for safe reinitialization. It does not free or allocate memory, but resets all fields related to memory layout, statistics, growth policies, debugging, and hooks.
Specifically, it:
arena_stats_reset().Use this when:
| arena | Pointer to the t_arena structure to reset. |
Definition at line 241 of file arena_internal.c.
References ARENA_ID_LEN, and arena_stats_reset().
| size_t default_grow_cb | ( | size_t | current_size, |
| size_t | requested_size | ||
| ) |
#include <arena_internal.h>
Default growth policy callback for arena resizing.
Default growth strategy for arenas that support dynamic resizing.
Computes the next size for an arena that needs to grow. The result is typically a geometric increase (e.g., 2x rule), optionally adjusted to accommodate the requested size.
| current_size | The current buffer size of the arena. |
| requested_size | The size that triggered the growth. |
This function computes a new arena size when a memory allocation request exceeds the current capacity. The growth strategy works as follows:
current_size + requested_size.SIZE_MAX), it falls back to a minimal sufficient size.This strategy offers exponential growth (geometric progression) to minimize reallocations and fragmentation.
| current_size | Current size of the arena in bytes. |
| requested_size | Additional memory needed for the new allocation. |
SIZE_MAX on overflow.arena->grow_cb. For example, use a fixed increment strategy instead of exponential growth if your use case favors more predictable memory sizing or tighter control over memory usage:Reasons to use a custom strategy:
Definition at line 78 of file arena_internal.c.
|
inlinestatic |
#include <arena_math.h>
Return the next power of two greater than or equal to x.
If x is already a power of two, it is returned unchanged. If x is zero, the function returns 1.
This is implemented using bitwise operations for speed and portability.
| x | The input value. |
x. Definition at line 116 of file arena_math.h.
|
inlinestatic |
#include <arena_math.h>
Perform a checked multiplication of two size_t values.
Computes a * b and stores the result in *result. If the multiplication would overflow SIZE_MAX, the function returns true and does not modify *result.
If the platform supports __builtin_mul_overflow, it will be used for fast hardware-checked overflow detection. Otherwise, a portable fallback is used.
| a | First operand. |
| b | Second operand. |
| result | Output pointer to store the product if safe. |
true if the multiplication would overflow, false otherwise.Definition at line 79 of file arena_math.h.