Version 7.0
Copyright © 2021 Lowell D. Thomas
APG
… an ABNF Parser Generator
Data Structures | Functions
memory.c File Reference

The memory management object. More...

#include "./lib.h"
#include <stdarg.h>
Include dependency graph for memory.c:

Go to the source code of this file.

Data Structures

struct  mem_cell_tag
 A circularly-linked list structure. More...
 
struct  mem
 For internal use only. The memory object's context. Opaque to user applications. More...
 

Functions

void * vpMemCtor (exception *spException)
 Construct a memory component. More...
 
void vMemDtor (void *vpCtx)
 Destroys a Memory component. Frees all memory allocated. More...
 
abool bMemValidate (void *vpCtx)
 Validates a memory context. More...
 
exceptionspMemException (void *vpCtx)
 Get a pointer to this memory objects's exception handler. More...
 
void * vpMemAlloc (void *vpCtx, aint uiBytes)
 Allocates memory. More...
 
void vMemFree (void *vpCtx, const void *vpData)
 Free memory previously allocated with vpMemAlloc(). More...
 
void * vpMemRealloc (void *vpCtx, const void *vpData, aint uiBytes)
 Re-allocates memory previously allocated with vpMemAlloc(). More...
 
aint uiMemCount (void *vpCtx)
 Returns the number of memory allocations. More...
 
void vMemClear (void *vpCtx)
 Frees all memory allocations. More...
 
void vMemStats (void *vpCtx, mem_stats *spStats)
 Returns a copy of the Memory component's current statistics. More...
 

Statistics Collection Macros used by the memory object.

If APG_MEM_STATS is defined, these 3 macros will be defined to call the statistics gathering functions. If APG_MEM_STATS is not defined, these macros generate no code.

#define STATS_ALLOC(s, i)   vStatsAlloc((s), (i))
 Called by the memory object to count memory allocations. More...
 
#define STATS_FREE(s, i)   vStatsFree((s), (i))
 Called by the memory object to count memory frees. More...
 
#define STATS_REALLOC(s, i, o)   vStatsRealloc((s), (i), (o))
 Called by the memory object to count memory re-allocations. More...
 

Detailed Description

The memory management object.

This file holds the memory management class or object. Almost all APG objects and applications use this memory object for control of all memory allocations and frees. A primary feature of this object is that its destruction automatically frees all memory allocations that have been made with it. Memory allocation failures are reported with an exception thrown to the parent application's catch block. This frees the application of all the burdensome code for checking the return and handling an error for each and every allocation.

Definition in file memory.c.

Macro Definition Documentation

◆ STATS_ALLOC

#define STATS_ALLOC (   s,
 
)    vStatsAlloc((s), (i))

Called by the memory object to count memory allocations.

Definition at line 84 of file memory.c.

◆ STATS_FREE

#define STATS_FREE (   s,
 
)    vStatsFree((s), (i))

Called by the memory object to count memory frees.

Definition at line 88 of file memory.c.

◆ STATS_REALLOC

#define STATS_REALLOC (   s,
  i,
 
)    vStatsRealloc((s), (i), (o))

Called by the memory object to count memory re-allocations.

Definition at line 92 of file memory.c.

Function Documentation

◆ bMemValidate()

abool bMemValidate ( void *  vpCtx)

Validates a memory context.

Parameters
vpCtxA pointer to a memory context.
Returns
APG_TRUE if the handle is valid, APG_FALSE otherwise.

Definition at line 160 of file memory.c.

◆ spMemException()

exception* spMemException ( void *  vpCtx)

Get a pointer to this memory objects's exception handler.

Parameters
vpCtxA pointer to a valid memory context previously returned from vpMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
Returns
Pointer to this memory object's exception structure

Definition at line 174 of file memory.c.

◆ uiMemCount()

aint uiMemCount ( void *  vpCtx)

Returns the number of memory allocations.

Parameters
vpCtxA pointer to a valid memory context previously returned from vpMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
Returns
Current number of allocations. vExContext() exception thrown if context pointer is invalid.

Definition at line 342 of file memory.c.

◆ vMemClear()

void vMemClear ( void *  vpCtx)

Frees all memory allocations.

Parameters
vpCtxA pointer to a valid memory context previously returned from vpMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.

Definition at line 361 of file memory.c.

◆ vMemDtor()

void vMemDtor ( void *  vpCtx)

Destroys a Memory component. Frees all memory allocated.

Parameters
vpCtxA pointer to a valid memory context previously returned from vpMemCtor(). Silently ignored if NULL. However, if non-NULL it must be a valid memory context pointer.

Definition at line 141 of file memory.c.

◆ vMemFree()

void vMemFree ( void *  vpCtx,
const void *  vpData 
)

Free memory previously allocated with vpMemAlloc().

Parameters
vpCtxA pointer to a valid memory context previously returned from vpMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
vpDataPointer to the data to free. A NULL pointer is silently ignored. However, an invalid pointer - a pointer not previously returned from vpMemAlloc() or vpMemRealloc() - will result in a thrown exception. vExContext() exception thrown if context pointer is invalid.

Definition at line 226 of file memory.c.

◆ vMemStats()

void vMemStats ( void *  vpCtx,
mem_stats spStats 
)

Returns a copy of the Memory component's current statistics.

Parameters
vpCtxA pointer to a valid memory context previously returned from vpMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
spStatspointer to a user-supplied statistics buffer.
Returns
void

Definition at line 456 of file memory.c.

◆ vpMemAlloc()

void* vpMemAlloc ( void *  vpCtx,
aint  uiBytes 
)

Allocates memory.

Note that uiBytes + sizeof(mem_cell) is actually allocated on the heap.

  • The data is | cell struct | ... user data ... |
  • The actual malloc() heap allocation is at cell struct
  • The user data area is at heap allocation address + sizeof(cell struct)
    Parameters
    vpCtxA pointer to a valid memory context previously returned from vpMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
    uiBytesthe number of bytes of memory to allocate
    Returns
    a pointer to the user data portion of the allocated memory. Exception thrown on memory allocation failure.

Definition at line 196 of file memory.c.

◆ vpMemCtor()

void* vpMemCtor ( exception spException)

Construct a memory component.

Parameters
spExceptionPointer to a valid exception structure initialized with vExCtor() or XCTOR(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
Returns
Pointer to a memory object context on success. Throws exception on memory allocation failure.

Definition at line 121 of file memory.c.

◆ vpMemRealloc()

void* vpMemRealloc ( void *  vpCtx,
const void *  vpData,
aint  uiBytes 
)

Re-allocates memory previously allocated with vpMemAlloc().

Can be used to up-size or down-size a memory allocation. Any previous data in the memory allocation is copied to the re-allocation.

Parameters
vpCtxA pointer to a valid memory context previously returned from vpMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
vpDataPointer to the data to free. An invalid pointer - a pointer not previously returned from vpMemAlloc() or vpMemRealloc() - will result in a thrown exception.
uiBytesnumber of re-allocated bytes of memory. Must be > 0;
Returns
pointer to the re-allocated memory. Throws exception on memory allocation error, invalid data pointer error or uiBytes=0.

Definition at line 268 of file memory.c.

APG Version 7.0 is licensed under the 2-Clause BSD License,
an Open Source Initiative Approved License.