|
memory_arena
|
Public API for acquiring and releasing temporary memory arenas from a pool. More...
Files | |
| file | arena_scratch.c |
| Implementation of scratch arena pool system for temporary, fast, and reusable allocations. | |
| file | arena_scratch.h |
| Scratch arena pool system for fast, reusable temporary allocations. | |
Data Structures | |
| struct | s_scratch_arena_pool |
| Scratch arena pool structure holding multiple reusable memory arenas. More... | |
Typedefs | |
| typedef struct s_scratch_arena_pool | t_scratch_arena_pool |
| Scratch arena pool structure holding multiple reusable memory arenas. | |
Functions | |
| t_arena * | scratch_acquire (t_scratch_arena_pool *pool) |
| Acquire a temporary scratch arena from the pool. | |
| void | scratch_pool_destroy (t_scratch_arena_pool *pool) |
| Destroy all arenas in a scratch pool and reset its metadata. | |
| bool | scratch_pool_init (t_scratch_arena_pool *pool, size_t slot_size, bool thread_safe) |
| Initialize a scratch arena pool with pre-allocated slots. | |
| void | scratch_release (t_scratch_arena_pool *pool, t_arena *arena) |
| Release a scratch arena back to the pool for reuse. | |
Public API for acquiring and releasing temporary memory arenas from a pool.
Scratch arenas are useful for high-frequency temporary allocations in performance-critical paths. These APIs support fast, reusable memory arenas from a preallocated pool with optional thread safety.
| struct s_scratch_arena_pool |
Scratch arena pool structure holding multiple reusable memory arenas.
This structure maintains a fixed number of scratch slots that can be individually acquired and reset for temporary memory needs.
Definition at line 89 of file arena_scratch.h.
Collaboration diagram for s_scratch_arena_pool:| Data Fields | ||
|---|---|---|
| pthread_mutex_t | lock | Mutex for protecting slot access. |
| size_t | slot_size | Size of each arena in bytes. |
| t_scratch_slot | slots[SCRATCH_MAX_SLOTS] | Array of scratch slots. |
| bool | thread_safe | Whether locking is enabled. |
| typedef struct s_scratch_arena_pool t_scratch_arena_pool |
#include <arena_scratch.h>
Scratch arena pool structure holding multiple reusable memory arenas.
This structure maintains a fixed number of scratch slots that can be individually acquired and reset for temporary memory needs.
| t_arena * scratch_acquire | ( | t_scratch_arena_pool * | pool | ) |
#include <arena_scratch.h>
Acquire a temporary scratch arena from the pool.
| pool | Pointer to the scratch arena pool to acquire from. |
t_arena, or NULL if none are free.This function returns a pointer to a scratch arena from the given pool that is currently available (i.e., not in use). Internally, it scans the pool’s slots and uses an atomic flag to claim one safely, even in multithreaded contexts.
Upon successful acquisition:
atomic_exchange().arena_reset() before returning.If no arenas are available, the function returns NULL and reports an error. This may happen when all slots are concurrently in use or exhausted.
| pool | Pointer to the scratch arena pool to acquire from. |
t_arena if one is available, or NULL on failure.scratch_release() when no longer needed.Definition at line 350 of file arena_scratch.c.
References s_scratch_slot::arena, arena_report_error(), arena_reset(), s_scratch_slot::in_use, SCRATCH_LOCK, SCRATCH_MAX_SLOTS, SCRATCH_UNLOCK, and s_scratch_arena_pool::slots.
| void scratch_pool_destroy | ( | t_scratch_arena_pool * | pool | ) |
#include <arena_scratch.h>
Destroy all arenas in a scratch pool and reset its metadata.
| pool | Pointer to the scratch arena pool to destroy. |
This function deinitializes all scratch arenas in the pool by calling arena_destroy() on each slot. If the pool was initialized as thread-safe, it also destroys the associated mutex.
After cleanup, the pool's memory is zeroed out using memset to prevent accidental reuse or access to invalidated arenas.
This function must be called before deallocating or discarding a scratch pool, especially in cases where initialization (scratch_pool_init) succeeded only partially or the pool is no longer needed.
| pool | Pointer to the scratch arena pool to destroy. |
NULL pool is safe and has no effect.Definition at line 302 of file arena_scratch.c.
References s_scratch_slot::arena, arena_destroy(), s_scratch_arena_pool::lock, SCRATCH_MAX_SLOTS, s_scratch_arena_pool::slots, and s_scratch_arena_pool::thread_safe.
| bool scratch_pool_init | ( | t_scratch_arena_pool * | pool, |
| size_t | slot_size, | ||
| bool | thread_safe | ||
| ) |
#include <arena_scratch.h>
Initialize a scratch arena pool with pre-allocated slots.
| pool | Pointer to the scratch pool structure to initialize. |
| slot_size | Size of each individual scratch arena (in bytes). |
| thread_safe | If true, enables mutex-based locking for slot access. |
true if the pool was successfully initialized, false otherwise.This function sets up a reusable pool of scratch arenas, each initialized to the same slot_size. It prepares the internal array of slots, resets metadata, and (if enabled) configures a mutex for thread safety.
For each slot:
slot_size.If any arena initialization fails, the entire pool is destroyed via scratch_pool_destroy() and the function returns false.
| pool | Pointer to the scratch pool structure to initialize. |
| slot_size | Size of each individual scratch arena (in bytes). |
| thread_safe | If true, enables mutex-based locking for slot access. |
true if the pool was successfully initialized, false otherwise.scratch_pool_destroy() to clean up the pool before deallocating it.Definition at line 249 of file arena_scratch.c.
References arena_report_error(), s_scratch_arena_pool::lock, SCRATCH_MAX_SLOTS, scratch_pool_destroy(), scratch_slot_init(), s_scratch_arena_pool::slot_size, s_scratch_arena_pool::slots, and s_scratch_arena_pool::thread_safe.
| void scratch_release | ( | t_scratch_arena_pool * | pool, |
| t_arena * | arena | ||
| ) |
#include <arena_scratch.h>
Release a scratch arena back to the pool for reuse.
| pool | Pointer to the scratch pool the arena belongs to. |
| arena | Pointer to the arena to release. |
This function marks a previously acquired scratch arena as available again. It searches the pool’s slots for a match with the provided arena pointer, and clears the in_use flag using atomic_store().
This allows the arena to be reused by future calls to scratch_acquire().
If the provided arena does not match any slot in the pool, the function logs an error via arena_report_error() and does nothing.
| pool | Pointer to the scratch pool the arena belongs to. |
| arena | Pointer to the arena to release. |
scratch_acquire() calls may cause logic errors.scratch_acquire(). Passing an invalid or mismatched pointer results in an error.Definition at line 398 of file arena_scratch.c.
References s_scratch_slot::arena, arena_report_error(), s_scratch_slot::in_use, SCRATCH_MAX_SLOTS, and s_scratch_arena_pool::slots.