About

The MAXON API provides tools to safely allocate new memory. Typically it is not needed to allocate raw memory, structures like maxon::BaseArray should be used instead (see BaseArray Manual). Memory is allocated using different allocators.

For object creation see Entity Creation.

Allocation

These macros allocate raw memory using the maxon::DefaultAllocator:

NewMem(): Returns the newly allocated memory.
NewMemClear(): Returns the newly allocated and cleared memory.
ReallocMem(): Resizes the given raw memory block.

To safely handle memory one can use references, see maxon::AutoMem in References.

Alternatively one can use the finally macro to ensure the release of memory, see Finally.

  // This example allocates raw memory and stores it with AutoMem.
 
  // allocate memory
  maxon::AutoMem<maxon::Char> data = NewMemClear(maxon::Char, count) iferr_return;
 
  // use memory
  for (maxon::Int i = 0; i < count; ++i)
    data[i] = (maxon::Char)i;
 
  // when the scope is left, maxon::AutoMem will free the memory

Memory Utility

Further memory utility tools are:

maxon::DeleteMem(): Frees the given raw memory block.
maxon::DeleteConstPtrMem(): Frees the given raw memory block defined with a const pointer.
maxon::MemCopy(): Copies raw memory to the given destination.
maxon::MemMove(): Moves raw memory to the given destination.
maxon::MemCopyType(): Copies the content of a data type to the given destination.
maxon::MemMoveType(): Moves the content of a data type to the given destination.
maxon::ClearMem(): Clears the given memory with pattern.
maxon::SecureClearMem(): Clears the given memory with pattern. It's guaranteed not to be removed by the compiler.
maxon::CompareMem(): Compares two memory blocks.
maxon::ClearMemType(): Clears memory of a data type with pattern.

  // This example allocates new memory. The memory content is written, copied and compared.
 
  maxon::Char* data = nullptr;
  maxon::Char* copy = nullptr;
 
  finally
  {
    // assure release of memory at the end
    DeleteMem(data);
    DeleteMem(copy);
  };
 
  // allocate memory
  data = NewMemClear(maxon::Char, count) iferr_return;
  copy = NewMemClear(maxon::Char, count) iferr_return;
 
  // use memory
  for (maxon::Int i = 0; i < count; ++i)
    data[i] = (maxon::Char)i;
 
  // copy data
  maxon::MemCopy(copy, data, count);
 
  // compare
  const maxon::Int res = maxon::CompareMem(data, copy, count);
  if (res == 0)
    DiagnosticOutput("Memory blocks are identical.");
 
  // clear memory
  maxon::SecureClearMem(data, count);

Allocators

An allocator allocates and releases memory. Typically the maxon::DefaultAllocator is used. In rare cases when special memory alignment is needed, a custom allocator can be used.

maxon::DefaultAllocator: The default allocator.
maxon::FixedBufferAllocator: Handles a fixed amount of memory on the stack. See maxon::BufferedBaseArray.
maxon::BlockBufferAllocator: Handles a given fixed memory block.
maxon::StackBufferAllocator: Used for a large number of allocations.
maxon::NullAllocator: An allocator that returns no memory.
maxon::CustomAllocatorInterface: Base interface for custom allocators.

If memory from the C standard lib is needed, use maxon::CStdLibAllocator.

  // This example uses FixedBufferAllocator to define a BaseArray type which guarantees a certain amout of memory.
 
  // define a BaseArray with guaranteed 1024 bytes from the stack
  using FixedBufferArray = maxon::BaseArray<maxon::Char, 16, maxon::BASEARRAYFLAGS::NONE, maxon::FixedBufferAllocator<maxon::Char, 1024, maxon::DefaultAllocator>>;
 
  // create array
  FixedBufferArray testArray;
 
  // check array size
  const maxon::Int size = (maxon::Int)SIZEOF(testArray);
  DiagnosticOutput("Size: @", size);
 
  // fill array
  // as long as the needed size is less than 1024, no memory calls are invoked
  for (maxon::Int i = 0; i < 1024; ++i)
  {
    testArray.Append() iferr_return;
  }

Table of Contents

About

Allocation

Memory Utility

Allocators

Further Reading