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 = ((4));
// ...

// or you can allocate the type directly

// Allocate a bunch of int's
int *intArray = (int *)(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-information 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
(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 *)(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-information.

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-information 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 an 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
(myMemory, 4096);

// or

// Clear a struct
(myStructPtr, sizeof(*myStructPtr));

// or

// Clear a fixed sized array
(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
(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 = (10);
(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
fplStructField	Defines a single field in a struct
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
fplGetAlignmentOffset	Returns the offset needed to satisfy an alignment boundary
fplGetAlignedSize	Extends a size to satisfy an alignment boundary
fplIsAligned	Returns true when a pointer address is aligned
fplStackAllocate	Allocates the given number of bytes on the stack
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