memory_arena
Loading...
Searching...
No Matches
Files | Data Structures | Typedefs | Functions
Scratch Arena Pool

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.
 

Detailed Description

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.


Data Structure Documentation

◆ s_scratch_arena_pool

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.

Examples
/home/toonsa/myProjects/memoryArena/srcs/core/arena_scratch.c.

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 Documentation

◆ 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.

Function Documentation

◆ scratch_acquire()

t_arena * scratch_acquire ( t_scratch_arena_pool *  pool)

#include <arena_scratch.h>

Acquire a temporary scratch arena from the pool.

Parameters
poolPointer to the scratch arena pool to acquire from.
Returns
Pointer to an available t_arena, or NULL if none are free.
See also
scratch_release

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:

  • The arena is marked as in-use via atomic_exchange().
  • Its memory is cleared using 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.

Parameters
poolPointer to the scratch arena pool to acquire from.
Returns
Pointer to a t_arena if one is available, or NULL on failure.
Note
The returned arena must be released using scratch_release() when no longer needed.
Warning
The arena is not thread-safe by default. Do not use the same scratch slot concurrently without external synchronization.
See also
scratch_release
arena_reset
Examples
/home/toonsa/myProjects/memoryArena/srcs/core/arena_scratch.c.

Definition at line 350 of file arena_scratch.c.

351{
352 if (!pool)
353 return arena_report_error(NULL, "scratch_acquire failed: pool is NULL"), NULL;
354
355 SCRATCH_LOCK(pool);
356 for (int i = 0; i < SCRATCH_MAX_SLOTS; ++i)
357 {
358 if (!atomic_exchange(&pool->slots[i].in_use, true))
359 {
360 arena_reset(&pool->slots[i].arena);
361 SCRATCH_UNLOCK(pool);
362 return &pool->slots[i].arena;
363 }
364 }
365 SCRATCH_UNLOCK(pool);
366 return arena_report_error(NULL, "scratch_acquire failed: all slots in use"), NULL;
367}
void arena_reset(t_arena *arena)
#define SCRATCH_UNLOCK(pool)
#define SCRATCH_MAX_SLOTS
Maximum number of concurrently usable scratch arenas in the pool.
#define SCRATCH_LOCK(pool)
Thread-safe locking macro (enabled only if ARENA_ENABLE_THREAD_SAFE is set)
void arena_report_error(t_arena *arena, const char *fmt,...)
Report an error from an arena using its configured error callback.
atomic_bool in_use
Atomic flag for acquisition tracking.
t_arena arena
Memory arena associated with this slot.
t_scratch_slot slots[SCRATCH_MAX_SLOTS]
Array of scratch slots.

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.

◆ scratch_pool_destroy()

void scratch_pool_destroy ( t_scratch_arena_pool *  pool)

#include <arena_scratch.h>

Destroy all arenas in a scratch pool and reset its metadata.

Parameters
poolPointer to the scratch arena pool to destroy.
Note
Must be called to clean up any internally allocated memory.
See also
scratch_pool_init

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.

Parameters
poolPointer to the scratch arena pool to destroy.
Returns
void
Note
This function is idempotent: calling it on a NULL pool is safe and has no effect.
See also
scratch_pool_init
arena_destroy
Examples
/home/toonsa/myProjects/memoryArena/srcs/core/arena_scratch.c.

Definition at line 302 of file arena_scratch.c.

303{
304 if (!pool)
305 return;
306
307 for (int i = 0; i < SCRATCH_MAX_SLOTS; ++i)
308 arena_destroy(&pool->slots[i].arena);
309
310#ifdef ARENA_ENABLE_THREAD_SAFE
311 if (pool->thread_safe)
312 pthread_mutex_destroy(&pool->lock);
313#endif
314
315 memset(pool, 0, sizeof(*pool));
316}
void arena_destroy(t_arena *arena)
pthread_mutex_t lock
Mutex for protecting slot access.
bool thread_safe
Whether locking is enabled.

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.

◆ scratch_pool_init()

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.

Parameters
poolPointer to the scratch pool structure to initialize.
slot_sizeSize of each individual scratch arena (in bytes).
thread_safeIf true, enables mutex-based locking for slot access.
Returns
true if the pool was successfully initialized, false otherwise.
See also
scratch_pool_destroy

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:

  • An arena is initialized with the specified slot_size.
  • The slot is marked as not in use.

If any arena initialization fails, the entire pool is destroyed via scratch_pool_destroy() and the function returns false.

Parameters
poolPointer to the scratch pool structure to initialize.
slot_sizeSize of each individual scratch arena (in bytes).
thread_safeIf true, enables mutex-based locking for slot access.
Returns
true if the pool was successfully initialized, false otherwise.
Note
All arenas in the pool are marked as growable by default.
Warning
You must call scratch_pool_destroy() to clean up the pool before deallocating it.
See also
scratch_slot_init
scratch_pool_destroy
scratch_acquire
scratch_release
Examples
/home/toonsa/myProjects/memoryArena/srcs/core/arena_scratch.c.

Definition at line 249 of file arena_scratch.c.

250{
251 if (!pool || slot_size == 0)
252 return arena_report_error(NULL, "scratch_pool_init failed: invalid arguments"), false;
253
254 memset(pool, 0, sizeof(*pool));
255 pool->slot_size = slot_size;
256 pool->thread_safe = thread_safe;
257
258#ifdef ARENA_ENABLE_THREAD_SAFE
259 if (thread_safe)
260 pthread_mutex_init(&pool->lock, NULL);
261#endif
262
263 for (int i = 0; i < SCRATCH_MAX_SLOTS; ++i)
264 {
265 if (!scratch_slot_init(&pool->slots[i], slot_size, i))
266 {
268 return false;
269 }
270 }
271 return true;
272}
static bool scratch_slot_init(t_scratch_slot *slot, size_t slot_size, int index)
Initialize a single scratch slot with its own arena.
size_t slot_size
Size of each arena in bytes.
void scratch_pool_destroy(t_scratch_arena_pool *pool)
Destroy all arenas in a scratch pool and reset its metadata.

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.

◆ scratch_release()

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.

Parameters
poolPointer to the scratch pool the arena belongs to.
arenaPointer to the arena to release.
See also
scratch_acquire

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.

Parameters
poolPointer to the scratch pool the arena belongs to.
arenaPointer to the arena to release.
Note
It is safe to call this function multiple times with the same arena, but doing so without matching scratch_acquire() calls may cause logic errors.
Warning
The arena must have been obtained from the same pool via scratch_acquire(). Passing an invalid or mismatched pointer results in an error.
See also
scratch_acquire
Examples
/home/toonsa/myProjects/memoryArena/srcs/core/arena_scratch.c.

Definition at line 398 of file arena_scratch.c.

399{
400 if (!pool || !arena)
401 {
402 arena_report_error(NULL, "scratch_release failed: null pool or arena");
403 return;
404 }
405
406 for (int i = 0; i < SCRATCH_MAX_SLOTS; ++i)
407 {
408 if (&pool->slots[i].arena == arena)
409 {
410 atomic_store(&pool->slots[i].in_use, false);
411 return;
412 }
413 }
414
415 arena_report_error(arena, "scratch_release failed: arena not found in pool");
416}

References s_scratch_slot::arena, arena_report_error(), s_scratch_slot::in_use, SCRATCH_MAX_SLOTS, and s_scratch_arena_pool::slots.