Skip to content

dtheaper

Heap allocation with embedded length and validation.

This group of functions provides heap allocation with tracked length for raw buffers. It is used inside other modules when they need explicit ownership and size validation of allocations. It serves to centralize allocation, clearing, and release behind a small API.

Each alloc/free pair updates a ledger channel named "dtheaper" to track current and peak memory usage.

Mini-guide

  • Allocate buffers through dtheaper_alloc() to get heap memory for your program to use.
  • Use the zeroing allocator when callers require cleared memory by performing fill at allocation.
  • Free buffers only via dtheaper_free() to maintain ledger consistency.

Example

void* buffer = NULL;
dterr_t* err = NULL;

err = dtheaper_alloc_and_zero(128, "example buffer", &buffer);
if (err != NULL)
{
    dtheaper_free(buffer);
    return;
}

err = dtheaper_fill(buffer, 0xAA);
if (err != NULL)
{
    dtheaper_free(buffer);
    return;
}

dtheaper_free(buffer);

Data structures

Functions

dtheaper_alloc

Allocates a heap buffer with embedded length metadata and returns the payload pointer.

Params:

int32_t length Number of payload bytes to allocate.
const char* why Descriptive string used for allocation tracking.
void** payload Receives the allocated payload pointer.

Return: dterr_t* Error object on failure, or NULL on success.

dtheaper_alloc_and_zero

Allocates a heap buffer and initializes its contents to zero.

Params:

int32_t length Number of payload bytes to allocate.
const char* why Descriptive string used for allocation tracking.
void** payload Receives the allocated payload pointer.

Return: dterr_t* Error object on failure, or NULL on success.

dtheaper_fill

Fills an allocated buffer using the stored length metadata.

Params:

void* buffer Payload pointer previously returned by the allocator.
uint8_t value Byte value to fill the buffer with.

Return: dterr_t* Error object if the buffer header is invalid, or NULL on success.

dtheaper_free

Releases an allocated buffer after clearing its metadata.

Params:

void* buffer Payload pointer previously returned by the allocator.

Return: void No return value.