Wizard's Toolkit - C API for the Wizard's Toolkit: Memory Allocation/Deallocation

AcquireCriticalMemory • AcquireAlignedMemory • AcquireVirtualMemory • AcquireWizardMemory • AcquireQuantumMemory • CopyWizardMemory • GetWizardMemoryMethods • GetVirtualMemoryBlob • RelinquishAlignedMemory • RelinquishVirtualMemory • RelinquishWizardMemory • ResetWizardMemory • ResizeWizardMemory • ResizeQuantumMemory • SetWizardMemoryMethods

AcquireCriticalMemory

AcquireCriticalMemory(): allocate a small memory request with AcquireMagickMemory(), however, on fail throw a fatal exception and exit. Free the memory reserve with RelinquishMagickMemory(). AcquireAlignedMemory(): allocate a small memory request that is aligned on a cache line. On fail, return NULL for possible recovery. Free the memory reserve with RelinquishMagickMemory(). AcquireMagickMemory()/ResizeMagickMemory(): allocate a small to medium memory request, typically with malloc()/realloc(). On fail, return NULL for possible recovery. Free the memory reserve with RelinquishMagickMemory(). AcquireQuantumMemory()/ResizeQuantumMemory(): allocate a small to medium memory request. This is a secure memory allocator as it accepts two parameters, count and quantum, to ensure the request does not overflow. It also check to ensure the request does not exceed the maximum memory per the security policy. Free the memory reserve with RelinquishMagickMemory(). AcquireVirtualMemory(): allocate a large memory request either in heap, memory-mapped, or memory-mapped on disk depending on whether heap allocation fails or if the request exceeds the maximum memory policy. Free the memory reserve with RelinquishVirtualMemory(). ResetMagickMemory(): fills the bytes of the memory area with a constant byte.

In addition, we provide hooks for your own memory constructor/destructors.

utilize our internal custom allocator as follows

Segregate our memory requirements from any program that calls our API. This should help reduce the risk of others changing our program state or causing memory corruption.

Our custom memory allocation manager implements a best-fit allocation policy using segregated free lists. It uses a linear distribution of size classes for lower sizes and a power of two distribution of size classes at higher sizes. It is based on the paper, "Fast Memory Allocation using Lazy Fits." written by Yoo C. Chung.

By default, ANSI memory methods are called (e.g. malloc). Use the custom memory allocator by defining WIZARDSTOOLKIT_EMBEDDABLE_SUPPORT to allocate memory with private anonymous mapping rather than from the heap.

AcquireAlignedMemory

AcquireAlignedMemory() returns a pointer to a block of memory at least size bytes whose address is aligned on a cache line or page boundary.

The format of the AcquireAlignedMemory method is:

void *AcquireAlignedMemory(const size_t count,const size_t quantum)

A description of each parameter follows:

count: the number of quantum elements to allocate.
quantum: the number of bytes in each quantum.

AcquireVirtualMemory

AcquireVirtualMemory() allocates a pointer to a block of memory at least size bytes suitably aligned for any use.

The format of the AcquireVirtualMemory method is:

MemoryInfo *AcquireVirtualMemory(const size_t count,const size_t quantum,
  ExceptionInfo *exception)

A description of each parameter follows:

count: the number of quantum elements to allocate.
quantum: the number of bytes in each quantum.

AcquireWizardMemory

AcquireWizardMemory() returns a pointer to a block of memory at least size bytes suitably aligned for any use.

The format of the AcquireWizardMemory method is:

void *AcquireWizardMemory(const size_t size)

A description of each parameter follows:

size: the size of the memory in bytes to allocate.

AcquireQuantumMemory

AcquireQuantumMemory() returns a pointer to a block of memory at least count * quantum bytes suitably aligned for any use.

The format of the AcquireQuantumMemory method is:

void *AcquireQuantumMemory(const size_t count,const size_t quantum)

A description of each parameter follows:

count: the number of quantum elements to allocate.
quantum: the number of bytes in each quantum.

CopyWizardMemory

CopyWizardMemory() copies size bytes from memory area source to the destination. Copying between objects that overlap will take place correctly. It returns destination.

The format of the CopyWizardMemory method is:

void *CopyWizardMemory(void *destination,const void *source,
  const size_t size)

A description of each parameter follows:

destination: the destination.
source: the source.
size: the size of the memory in bytes to allocate.

GetWizardMemoryMethods

GetWizardMemoryMethods() gets the methods to acquire, resize, and destroy memory.

The format of the GetWizardMemoryMethods() method is:

void GetWizardMemoryMethods(AcquireMemoryHandler *acquire_memory_handler,
  ResizeMemoryHandler *resize_memory_handler,
  DestroyMemoryHandler *destroy_memory_handler)

A description of each parameter follows:

acquire_memory_handler: method to acquire memory (e.g. malloc).
resize_memory_handler: method to resize memory (e.g. realloc).
destroy_memory_handler: method to destroy memory (e.g. free).

GetVirtualMemoryBlob

GetVirtualMemoryBlob() returns the virtual memory blob associated with the specified MemoryInfo structure.

The format of the GetVirtualMemoryBlob method is:

void *GetVirtualMemoryBlob(const MemoryInfo *memory_info)

A description of each parameter follows:

memory_info: The MemoryInfo structure.

RelinquishAlignedMemory

RelinquishAlignedMemory() frees memory acquired with AcquireAlignedMemory() or reuse.

The format of the RelinquishAlignedMemory method is:

void *RelinquishAlignedMemory(void *memory)

A description of each parameter follows:

memory: A pointer to a block of memory to free for reuse.

RelinquishVirtualMemory

RelinquishVirtualMemory() destroys the MemoryInfo structure returned by a previous call to AcquireVirtualMemory().

The format of the RelinquishVirtualMemory method is:

void *RelinquishVirtualMemory(MemoryInfo *memory_info)

A description of each parameter follows:

memory_info: A pointer to a block of memory to free for reuse.

RelinquishWizardMemory

RelinquishWizardMemory() zeros memory that has been allocated, frees it for reuse.

The format of the RelinquishWizardMemory method is:

void *RelinquishWizardMemory(void *memory)

A description of each parameter follows:

memory: A pointer to a block of memory to free for reuse.

ResetWizardMemory

ResetWizardMemory() fills the first size bytes of the memory area pointed to by memory with the constant byte c. We use a volatile pointer when updating the byte string. Most compilers will avoid optimizing away access to a volatile pointer, even if the pointer appears to be unused after the call.

The format of the ResetWizardMemory method is:

void *ResetWizardMemory(void *memory,int c,const size_t size)

A description of each parameter follows:

memory: A pointer to a memory allocation.
c: Set the memory to this value.
size: Size of the memory to reset.

ResizeWizardMemory

ResizeWizardMemory() changes the size of the memory and returns a pointer to the (possibly moved) block. The contents will be unchanged up to the lesser of the new and old sizes.

The format of the ResizeWizardMemory method is:

void *ResizeWizardMemory(void *memory,const size_t size)

A description of each parameter follows:

memory: A pointer to a memory allocation.
size: the new size of the allocated memory.

ResizeQuantumMemory

ResizeQuantumMemory() changes the size of the memory and returns a pointer to the (possibly moved) block. The contents will be unchanged up to the lesser of the new and old sizes.

The format of the ResizeQuantumMemory method is:

void *ResizeQuantumMemory(void *memory,const size_t count,
  const size_t quantum)

A description of each parameter follows:

memory: A pointer to a memory allocation.
count: the number of quantum elements to allocate.
quantum: the number of bytes in each quantum.

SetWizardMemoryMethods

SetWizardMemoryMethods() sets the methods to acquire, resize, and destroy memory.

The format of the SetWizardMemoryMethods() method is:

SetWizardMemoryMethods(AcquireMemoryHandler acquire_memory_handler,
  ResizeMemoryHandler resize_memory_handler,
  DestroyMemoryHandler destroy_memory_handler)

A description of each parameter follows:

acquire_memory_handler: method to acquire memory (e.g. malloc).
resize_memory_handler: method to resize memory (e.g. realloc).
destroy_memory_handler: method to destroy memory (e.g. free).