Skip to content

dtbuffer

Heap-backed buffer descriptor for explicit ownership control

This group of functions provides heap buffer utilities for small, explicit data moves. It is intended for code that needs to model ownership and lifetime of byte payloads explicitly. The implementation has simple contiguous allocation with optional payload wrapping.

Each create/dispose pair updates a ledger channel named "dtbuffer" to track current and peak memory usage.

Mini-guide

  • Create an owning buffer by calling dtbuffer_create, to allocate a single heap block containing both descriptor and payload by allocating heap memory.
  • Wrap an existing payload by calling dtbuffer_wrap, which borrows the caller-provided memory by storing the pointer without taking ownership.
  • Dispose every buffer with dtbuffer_dispose to ensure memory release and update of the ledger.
  • Treat the payload field as mutable storage, because the API exposes a writable pointer and does not perform internal copying.

Example

dtbuffer_t* buf = NULL;
dterr_t* err = dtbuffer_create(&buf, 128);
memset(buf->payload, 0, buf->length);
if (err == NULL)
{
    /* use buf->payload and buf->length */
    dtbuffer_dispose(buf);
}

Data structures

dtbuffer_t

Describes a byte buffer with explicit ownership semantics.

Members:

void* payload Owned or borrowed payload bytes; NULL when empty.
int32_t length Number of bytes currently exposed through payload.
int32_t flags Bitwise flags describing how the buffer was initialized.

Functions

dtbuffer_create

Allocates a buffer descriptor and payload as a single heap block. This is the alternate to dtbuffer_wrap, which borrows caller-managed memory.

Params:

dtbuffer_t** self Receives the newly allocated buffer descriptor.
int32_t length Number of payload bytes to allocate.

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

dtbuffer_dispose

Releases buffer resources according to how the buffer was initialized. Updates ledger.

Params:

dtbuffer_t* self Buffer to dispose.

Return: void No return value.

dtbuffer_wrap

Initializes a buffer descriptor to reference an existing payload. This is the alternate to dtbuffer_create, which allocates both descriptor and payload together.

Params:

dtbuffer_t* self Buffer descriptor to initialize.
void* payload Caller-managed payload memory.
int32_t length Number of bytes exposed through the payload.

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