Final Platform Layer  0.9.6-beta
Memory handling

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
fplMegaBytes
#define fplMegaBytes(value)
Returns the number of bytes for the given megabytes.
Definition: final_platform_layer.h:2232
fplMemoryAlignedAllocate
fpl_common_api void * fplMemoryAlignedAllocate(const size_t size, const size_t alignment)
Allocates aligned memory from the operating system by the given alignment.
fplKiloBytes
#define fplKiloBytes(value)
Returns the number of bytes for the given kilobytes.
Definition: final_platform_layer.h:2230
fplMemoryFree
fpl_platform_api void fplMemoryFree(void *ptr)
Releases the memory allocated from the operating system.
fplMemoryCopy
fpl_common_api void fplMemoryCopy(const void *sourceMem, const size_t sourceSize, void *targetMem)
Copies the given source memory with its length to the target memory.
fplMemoryClear
fpl_common_api void fplMemoryClear(void *mem, const size_t size)
Clears the given memory by the given size to zero.
fplMemorySet
fpl_common_api void fplMemorySet(void *mem, const uint8_t value, const size_t size)
Sets the given memory by the given size to the given value.
fplMemoryAllocate
fpl_platform_api void * fplMemoryAllocate(const size_t size)
Allocates memory from the operating system by the given size.