Memory handling

Table of Contents

• Default/Unaligned memory allocation
  • Allocate (n)-bytes of memory
  • Free memory
  • Data layout of default/unaligned memory
• Custom aligned memory allocation
  • Allocate custom aligned (n)-bytes of memory
  • Free aligned memory
  • Data layout of aligned memory
• Memory operations
  • Clear (n)-bytes of memory
  • Overwrite (n)-bytes of memory with a given value
  • Copy (n)-bytes of memory to another memory location
• Useful macro functions

FPL provides a couple of functions to allocate/set/clear memory for you.
You are free to use it as you like, but you can use malloc(), free() as well if you want to.

Default/Unaligned memory allocation

Allocate (n)-bytes of memory

To allocate a block of contiguous memory, you simply call fplMemoryAllocate() with the number of bytes you want to allocate.
This will return a pointer you can start to write into.

// Allocate 4MB of memory
void *myMemory = fplMemoryAllocate(fplMegaBytes(4));
// ...
 
// or you can allocate the type directly
 
// Allocate a bunch of int's
int *intArray = (int *)fplMemoryAllocate(sizeof(int) * 100000);
intArray[0] = 42;
// ...

Note

This function does nothing more than calling the proper operating-system function such as VirtualAlloc() or mmap() .

Attention

The memory is not guaranteed to be aligned, but depending on the OS it may be aligned to something.

Warning

Do not write before this pointer, otherwise, you may overwrite meta-informations required for releasing the memory later on.

Free memory

To free memory, you simply call fplMemoryFree() with the base pointer of your memory, and that's it.

// Free a memory block allocated by fplMemoryAllocate
fplMemoryFree(myMemory);

Warning

Do not call this function with a pointer allocated from fplMemoryAlignedAllocate() , otherwise, you will corrupt memory!

Data layout of default/unaligned memory

Here you can see the full data-layout for a default/unaligned memory block:

0 or 4/8 bytes for x86/x64	0 or 4/8 bytes for x86/x64	n-bytes
Optional size of the entire memory block	Optional padding	Memory of the data

Note

On Linux/Unix the size and small padding are stored before the actual data, because munmap() requires a size as a parameter as well.

Custom aligned memory allocation

Allocate custom aligned (n)-bytes of memory

To allocate a custom aligned block of contiguous memory, you simply call fplMemoryAlignedAllocate() with the number of bytes you want to allocate and the custom alignment.
This will return a guaranteed aligned pointer you can start to write into.

// Allocate a bunch of 4x4 matrices aligned by 16-bytes
typedef struct Mat4f {
    float m[16];
} Vec4f;
Mat4f *matrices = (Mat4f *)fplMemoryAlignedAllocate(sizeof(Mat4f) * 128, 16);
// ...

Note

The size of the memory block may be greater than the size you requested, due to alignment padding and meta-informations.

Attention

The alignment parameter must be a power-of-two based value, otherwise, the function will fail.

Warning

Do not write before this pointer, otherwise you will overwrite meta-informations required for releasing the memory later on.

Free aligned memory

To free aligned memory you simply call fplMemoryAlignedFree() with the base pointer of your aligned memory and that's it.

Warning

Do not call this function with a pointer allocated from fplMemoryAllocate() , otherwise, you will corrupt memory!

Data layout of aligned memory

Here you can see the full data-layout for a aligned memory block:

4/8 bytes for x86/x64	Alignment * 2 bytes	n-bytes
Address of the base-pointer	Alignment padding	Data layout

Memory operations

Clear (n)-bytes of memory

Call fplMemoryClear() to clear a memory block starting from the base-pointer with a given size.

// Clear 4-KB of memory to zero, starting by the given memory address
fplMemoryClear(myMemory, 4096);
 
// or
 
// Clear a struct
fplMemoryClear(myStructPtr, sizeof(*myStructPtr));
 
// or
 
// Clear a fixed sized array
fplMemoryClear(myArray, sizeof(myArray));

Note

This operation is executed in 8-bytes, 4-bytes, 2-bytes sized chunks to improve performance.

Overwrite (n)-bytes of memory with a given value

Call fplMemorySet() to overwrite a memory block starting from the base-pointer with a given size and the given value.

// Overwrites 1000 bytes of memory with a 8-bit value
fplMemorySet(myMemory, 0xAB, 1000);

Note

This operation is executed in 8-bytes, 4-bytes, 2-bytes sized chunks to improve performance.

Copy (n)-bytes of memory to another memory location

To copy (n)-bytes of memory you simply call fplMemoryCopy() with the source and destination pointer and the number of bytes you want to copy.

// Copy parts of memory into another memory
// void *destMemory was already allocated before
size_t numberOfBytesToCopy = fplKiloBytes(10);
fplMemoryCopy(sourceMemory, numberOfBytesToCopy, destMemory);

Note

This operation is executed in 8-bytes, 4-bytes, 2-bytes sized chunks to improve performance.

Useful macro functions

FPL provides a few macro functions useful for dealing with memory:

Name	What it does
fplZeroInit	Initializes a struct with zero
fplStructInit	Initializes a struct with values
fplStructSet	Overwrites a struct with the given value
fplClearStruct	Clears the given struct pointer to zero
fplCopyStruct	Copies the source struct data into the destination pointer
fplArrayCount	Returns the number of elements in fixed sized array
fplOffsetOf	Returns the byte-offset to a field in a struct
fplKiloBytes	Converts the given kilobytes value into bytes
fplMegaBytes	Converts the given megabytes value into bytes
fplGigaBytes	Converts the given gigabytes value into bytes
fplTeraBytes	Converts the given terabytes value into bytes