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

Functions for recording, retrieving, and printing memory usage statistics. More...

Files

file  arena_stats.c
 Arena statistics and diagnostics module.
 
file  arena_stats.h
 Runtime statistics tracking and diagnostics for memory arenas.
 

Data Structures

struct  s_arena_stats
 Structure holding runtime statistics for an arena. More...
 

Typedefs

typedef struct s_arena_stats t_arena_stats
 Structure holding runtime statistics for an arena.
 

Functions

t_arena_stats arena_get_stats (const t_arena *arena)
 Return a snapshot of the arena's internal statistics.
 
void arena_print_stats (t_arena *arena, FILE *stream)
 Print formatted diagnostics about the arena to a stream.
 
void arena_stats_record_growth (t_arena_stats *stats, size_t size)
 Append a new growth event to the growth_history array.
 
void arena_stats_reset (t_arena_stats *stats)
 Reset the given statistics structure to zero.
 

Detailed Description

Functions for recording, retrieving, and printing memory usage statistics.

This group provides introspection into arena usage patterns:

Useful for profiling, visualization, or custom allocator analytics.


Data Structure Documentation

◆ s_arena_stats

struct s_arena_stats

Structure holding runtime statistics for an arena.

Tracks all major allocation events, usage metrics, and debug counters. Fields are updated automatically by internal arena operations.

Definition at line 53 of file arena_stats.h.

Data Fields
size_t alloc_id_counter Total allocation ID counter (used for tracking)
size_t allocations Total number of successful allocations.
size_t bytes_allocated Cumulative bytes allocated.
size_t failed_allocations Number of failed allocation attempts.
size_t * growth_history Array of size values recorded during arena growth.
size_t growth_history_count Number of growth events recorded.
size_t last_alloc_id Unique ID of the last allocation.
size_t last_alloc_offset Offset of the last allocation.
size_t last_alloc_size Size of the last allocation.
size_t live_allocations Number of active allocations (not yet released)
size_t peak_usage Highest offset reached (i.e., peak memory usage)
size_t reallocations Total number of reallocations (via arena_realloc_last)
size_t shrinks Number of times the arena was shrunk.
size_t wasted_alignment_bytes Total bytes wasted due to alignment padding.

Typedef Documentation

◆ t_arena_stats

typedef struct s_arena_stats t_arena_stats

#include <arena_stats.h>

Structure holding runtime statistics for an arena.

Tracks all major allocation events, usage metrics, and debug counters. Fields are updated automatically by internal arena operations.

Function Documentation

◆ arena_get_stats()

t_arena_stats arena_get_stats ( const t_arena *  arena)

#include <arena_stats.h>

Return a snapshot of the arena's internal statistics.

Retrieve a snapshot of the current arena statistics.

Parameters
arenaPointer to the arena.
Returns
A copy of its t_arena_stats structure.
See also
arena_print_stats
arena_stats_reset

This function returns a copy of the t_arena_stats structure from the specified arena. The statistics include information such as:

  • Number of allocations and reallocations
  • Bytes allocated and alignment overhead
  • Peak usage and current allocation ID
  • Growth history and tracking counters

This is useful for diagnostics, profiling, logging, or exporting memory usage metrics to external tools.

The returned stats are safe to use outside the arena and will not be affected by future changes to the arena state.

Thread-safe: acquires the arena lock before reading the data.

Parameters
arenaPointer to the arena to inspect.
Returns
A copy of the arena’s current statistics. If arena is NULL, returns a zero-initialized t_arena_stats structure.
Note
This function performs a shallow copy. The growth_history pointer in the returned struct still points to internal memory managed by the arena. Do not modify or free it manually.
See also
arena_print_stats
arena_stats_record_growth
arena_stats_reset

Definition at line 218 of file arena_stats.c.

219{
220 t_arena_stats copy;
221 memset(&copy, 0, sizeof(copy));
222
223 if (!arena)
224 return copy;
225
226 ARENA_LOCK((t_arena*) arena);
227
228 copy = arena->stats;
229
230 ARENA_UNLOCK((t_arena*) arena);
231 return copy;
232}
#define ARENA_UNLOCK(arena)
#define ARENA_LOCK(arena)
Acquire the mutex lock if thread safety is enabled.
Structure holding runtime statistics for an arena.
Definition arena_stats.h:54
The main memory arena structure used for fast allocation.

References ARENA_LOCK, and ARENA_UNLOCK.

◆ arena_print_stats()

void arena_print_stats ( t_arena *  arena,
FILE *  stream 
)

#include <arena_stats.h>

Print formatted diagnostics about the arena to a stream.

Print detailed diagnostics about the given arena to a stream.

Parameters
arenaPointer to the arena to inspect.
streamStream to write the output to (e.g., stdout, stderr).
See also
arena_get_stats

This function outputs a formatted summary of the current arena state to the specified FILE* stream. It includes memory layout, allocation statistics, debug metadata, and growth history (if available).

Sections reported:

  • Basic layout: buffer address, size, offset, remaining space
  • Allocation stats: total allocations, reallocations, failures, alignment waste
  • Last allocation metadata: size, offset, ID
  • Debug info: ID, label, hook presence, thread safety
  • Growth history: sizes recorded during dynamic expansion

This function is useful for:

  • Debugging memory usage patterns
  • Verifying arena configuration at runtime
  • Profiling custom allocators using arena-backed systems
Parameters
arenaPointer to the arena to inspect.
streamOutput stream to write the diagnostics to (e.g., stdout, stderr, or a log file).
Returns
void
Note
If arena or stream is NULL, the function does nothing.

Definition at line 74 of file arena_stats.c.

75{
76 if (!arena || !stream)
77 return;
78
79 fprintf(stream, "──────────────────────────────\n");
80 fprintf(stream, " Arena Diagnostics (%s)\n", arena->debug.label ? arena->debug.label : "unnamed");
81 fprintf(stream, "──────────────────────────────\n");
82
83 // Buffer & memory layout
84 fprintf(stream, "- Buffer Address: %p\n", (void*) arena->buffer);
85 fprintf(stream, "- Buffer Size: %zu bytes\n", arena->size);
86 fprintf(stream, "- Current Offset: %zu bytes\n", arena->offset);
87 fprintf(stream, "- Remaining Space: %zu bytes\n", arena->size - arena->offset);
88 fprintf(stream, "- Peak Usage: %zu bytes\n", arena->stats.peak_usage);
89 fprintf(stream, "- Can Grow: %s\n",
90 atomic_load_explicit(&arena->can_grow, memory_order_acquire) ? "yes" : "no");
91
92 // Allocation tracking
93 fprintf(stream, "- Allocations: %zu\n", arena->stats.allocations);
94 fprintf(stream, "- Reallocations: %zu\n", arena->stats.reallocations);
95 fprintf(stream, "- Failed Allocations: %zu\n", arena->stats.failed_allocations);
96 fprintf(stream, "- Live Allocations: %zu\n", arena->stats.live_allocations);
97 fprintf(stream, "- Bytes Allocated: %zu bytes\n", arena->stats.bytes_allocated);
98 fprintf(stream, "- Wasted Alignment Bytes: %zu bytes\n", arena->stats.wasted_alignment_bytes);
99 fprintf(stream, "- Shrinks: %zu\n", arena->stats.shrinks);
100
101 // Last allocation details
102 fprintf(stream, "- Last Alloc Size: %zu bytes\n", arena->stats.last_alloc_size);
103 fprintf(stream, "- Last Alloc Offset: %zu\n", arena->stats.last_alloc_offset);
104 fprintf(stream, "- Last Alloc ID: %zu\n", arena->stats.last_alloc_id);
105
106 // Debug / internal metadata
107 fprintf(stream, "- Debug ID: %s\n", arena->debug.id);
108 fprintf(stream, "- Subarena Counter: %d\n", arena->debug.subarena_counter);
109 fprintf(stream, "- Hook Installed: %s\n", arena->hooks.hook_cb ? "yes" : "no");
110#ifdef ARENA_ENABLE_THREAD_SAFE
111 fprintf(stream, "- Thread Safety: %s\n", arena->use_lock ? "enabled" : "disabled");
112#endif
113
114 // Growth history
115 if (arena->stats.growth_history_count > 0)
116 {
117 fprintf(stream, "- Growth History: ");
118 for (size_t i = 0; i < arena->stats.growth_history_count; ++i)
119 fprintf(stream, "%zu ", arena->stats.growth_history[i]);
120 fprintf(stream, "\n");
121 }
122 else
123 {
124 fprintf(stream, "- Growth History: (none)\n");
125 }
126}

◆ arena_stats_record_growth()

void arena_stats_record_growth ( t_arena_stats *  stats,
size_t  new_size 
)

#include <arena_stats.h>

Append a new growth event to the growth_history array.

Record a new arena growth event in the statistics.

Parameters
statsPointer to the stats structure to update.
sizeThe new size of the arena after a growth.
See also
arena_print_stats

This function appends a new size value to the growth_history array inside the provided t_arena_stats structure. It tracks each time the arena grows dynamically (via arena_grow()), enabling tools and diagnostics to analyze memory usage trends over time.

Internally:

  • It reallocates the growth_history array to make room for the new entry.
  • Appends the new_size to the end of the list.
  • Increments the growth_history_count.

If memory reallocation fails, the function logs a debug message via ALOG (if debug logging is enabled) and exits silently without recording the growth.

Parameters
statsPointer to the t_arena_stats structure to update.
new_sizeThe new arena size (in bytes) after a growth operation.
Returns
void
Note
This function is typically called automatically by arena_grow(). The growth_history buffer is dynamically managed and grows linearly.
Warning
This function does nothing if stats is NULL. Memory allocation failure is non-fatal but results in data loss for this event.
See also
arena_grow
arena_print_stats

Definition at line 164 of file arena_stats.c.

165{
166 if (!stats)
167 return;
168
169 size_t count = stats->growth_history_count;
170 size_t* new_buffer = realloc(stats->growth_history, (count + 1) * sizeof(size_t));
171 if (!new_buffer)
172 {
173 ALOG("arena_stats_record_growth: failed to realloc for growth history\n");
174 return;
175 }
176
177 stats->growth_history = new_buffer;
178 stats->growth_history[count] = new_size;
179 stats->growth_history_count++;
180}
#define ALOG(...)
Debug logging macro (enabled only if ARENA_DEBUG_LOG is set).
size_t growth_history_count
Number of growth events recorded.
Definition arena_stats.h:62
size_t * growth_history
Array of size values recorded during arena growth.
Definition arena_stats.h:61

References ALOG, s_arena_stats::growth_history, and s_arena_stats::growth_history_count.

◆ arena_stats_reset()

void arena_stats_reset ( t_arena_stats *  stats)

#include <arena_stats.h>

Reset the given statistics structure to zero.

Reset all allocation statistics in an arena stats structure.

Parameters
statsPointer to the stats structure to reset.
Note
This does not affect the arena’s internal stats unless you explicitly assign it back.

This function clears all fields in a t_arena_stats structure, effectively resetting the arena's statistical tracking to an initial state.

It resets:

  • Allocation and reallocation counters.
  • Total bytes allocated and wasted.
  • Peak usage and live allocation tracking.
  • Last allocation metadata (size, offset, ID).
  • Growth history tracking and counter.

This is typically called during arena initialization or reuse.

Parameters
statsPointer to the t_arena_stats structure to reset.
Note
If stats is NULL, the function does nothing.
See also
arena_zero_metadata
Examples
/home/toonsa/myProjects/memoryArena/srcs/core/arena_create.c.

Definition at line 187 of file arena_internal.c.

188{
189 if (!stats)
190 return;
191
192 stats->allocations = 0;
193 stats->reallocations = 0;
194 stats->failed_allocations = 0;
195 stats->live_allocations = 0;
196 stats->bytes_allocated = 0;
197 stats->wasted_alignment_bytes = 0;
198 stats->shrinks = 0;
199 stats->peak_usage = 0;
200 stats->last_alloc_size = 0;
201 stats->last_alloc_offset = 0;
202 stats->last_alloc_id = (size_t) -1;
203 stats->alloc_id_counter = 0;
204 stats->growth_history = NULL;
205 stats->growth_history_count = 0;
206}
size_t last_alloc_size
Size of the last allocation.
Definition arena_stats.h:64
size_t shrinks
Number of times the arena was shrunk.
Definition arena_stats.h:60
size_t peak_usage
Highest offset reached (i.e., peak memory usage)
Definition arena_stats.h:58
size_t reallocations
Total number of reallocations (via arena_realloc_last)
Definition arena_stats.h:56
size_t failed_allocations
Number of failed allocation attempts.
Definition arena_stats.h:68
size_t wasted_alignment_bytes
Total bytes wasted due to alignment padding.
Definition arena_stats.h:59
size_t last_alloc_id
Unique ID of the last allocation.
Definition arena_stats.h:66
size_t bytes_allocated
Cumulative bytes allocated.
Definition arena_stats.h:57
size_t alloc_id_counter
Total allocation ID counter (used for tracking)
Definition arena_stats.h:67
size_t allocations
Total number of successful allocations.
Definition arena_stats.h:55
size_t live_allocations
Number of active allocations (not yet released)
Definition arena_stats.h:63
size_t last_alloc_offset
Offset of the last allocation.
Definition arena_stats.h:65

References s_arena_stats::alloc_id_counter, s_arena_stats::allocations, s_arena_stats::bytes_allocated, s_arena_stats::failed_allocations, s_arena_stats::growth_history, s_arena_stats::growth_history_count, s_arena_stats::last_alloc_id, s_arena_stats::last_alloc_offset, s_arena_stats::last_alloc_size, s_arena_stats::live_allocations, s_arena_stats::peak_usage, s_arena_stats::reallocations, s_arena_stats::shrinks, and s_arena_stats::wasted_alignment_bytes.