VCS Dev Docs File src/common/memory/memory.h

The memory subsystem interface.

More...

Functions

void*kmem_allocate(const int numBytes, const char *const reason)
kmem_release(void **mem)
uintkmem_sizeof_allocation(const void *const mem)

Detailed description

The memory subsystem interface.

The memory subsystem provides chunks of pre-allocated heap memory to the rest of VCS and its subsystems for storing blocks of POD data.

The subsystem allocates a fixed-size memory buffer on initialization and deals out portions of it as virtual allocations to callers. The subsystem also maintains internal bookkeeping of requested allocations, allowing for monitoring of VCS's memory usage.

Note:

A C++-style wrapper for this interface is provided by heap_mem.

Warning:

This memory interface is for POD data only; i.e. anything you wouldn't mind using memset() on.

Usage

  1. Call kmem_allocate() to request an allocation of memory:
    // Note: The allocator will 0-initialize the memory.char *bytes = (char*)kmem_allocate(101, "101 bytes");int *ints = (int*)kmem_allocate(2*sizeof(int), "A pair of ints"); // Use the allocated memory as you would a standard allocation.bytes[0] = 82;ints[1] = 1234;
  2. You can use kmem_sizeof_allocation() to find the size of an allocation:
    char *buffer = (char*)kmem_allocate(44);unsigned size = kmem_sizeof_allocation((void*)buffer);// size == 44.
  3. Call kmem_release() to release an allocation back into circulation for subsequent calls to kmem_allocate():
    char *buffer = (char*)kmem_allocate(1);// buffer != NULL. kmem_release((void**)&buffer);// buffer == NULL.

Function documentation

void* kmem_allocate(const int numBytes, const char *const reason)

Allocates a consecutive block of numBytes bytes and returns a pointer to the first byte. The block's bytes are 0-initialized.

The allocation is virtual in that no new memory is allocated; rather, the pointer returned is to an unused region of the memory subsystem's pre-allocated fixed-size memory buffer.

For bookkeeping and debugging purposes, reason gives a string briefly explaining the caller's intended purpose for the allocation (e.g. "Scratchbuffer").

Triggers an assertion failure if the allocation fails (e.g. if the memory subsystem's fixed-size buffer doesn't have enough room for the requested allocation).

// Allocate 101 bytes.char *buffer = (char*)kmem_allocate(101, "An example allocation");
Note:

The first runtime call to this function will cause the memory subsystem to initialize its fixed-size memory buffer. Any unrecoverable failure in this initialization (e.g. insufficient system memory) will result in an assertion failure or other such error condition.

kmem_release(void **mem)

Releases an allocation made with kmem_allocate().

The allocation is identified by mem, which is the pointer returned by kmem_allocate() for that allocation.

Note:

The value of the pointer passed in as mem will be set to NULL.

// Make an allocation.char *buffer = (char*)kmem_allocate(101, "An example allocation"); // buffer != NULL. // Release the allocation.kmem_release((void**)&buffer); // buffer == NULL.
See also kmem_allocate()

uint kmem_sizeof_allocation(const void *const mem)

Returns the size (in number of bytes) of an allocation made with kmem_allocate().

The allocation is identified by mem, which is the pointer returned by kmem_allocate() for that allocation.

char *buffer = (char*)kmem_allocate(101, "An example allocation"); unsigned size = kmem_sizeof_allocation((void*)buffer);// size == 101.
See also kmem_allocate()