Memory handling functions
This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core
The PFI provides the following types of functions for handling memory:
Allocating memory
The following function should be called to allocate memory:
void* PlgFwMemAlloc(size_t cbSize, uint32 fAllocFlags);
Given a byte count (cbSize)
, PlgFwMemAlloc
dynamically allocates memory from the RIP's heap storage.
The parameter fAllocFlags
contains a set of bit flags which refine the behavior of the function. The defined flags are as follows:
| If the allocation fails, return |
| Initialize allocated memory with zeros. |
| Leave allocated memory un‐initialized. |
If fAllocFlags
includes FWMEM_ALLOC_FAIL_NULL
, the function will return NULL
if the memory allocation fails. All calls to PlgFwMemAlloc
should set FWMEM_ALLOC_FAIL_NULL
,
as no alternative behavior is presently defined.
All calls to PlgFwMemAlloc
should also set either PLGFWMEM_INIT_UNSPECIFIED
or PLGFWMEM_INIT_ZEROED
. These two flags specify whether allocated memory should be initialized by setting all bytes to zero or should be left uninitialized.
For ease of development, a plugin developer can redefine malloc()
using the following macro:
#define malloc(n) \ PlgFwMemAlloc( \
(size_t)(n), \
(PLGFWMEM_ALLOC_FAIL_NULL | PLGFWMEM_INIT_UNSPECIFIED))
Freeing memory
The following function should be called to free memory that has been allocated using PlgFwMemAlloc
: void PlgFwMemFree(void *pBlock);
The function should be passed a pointer to memory previously allocated by PlgFwMemAlloc
, and will
deallocate that memory and free it back to the RIP's heap. Partial de‐allocations cannot be performed. It is an error to call PlgFwMemFree
() with a NULL
pointer.
For ease of development, a plugin developer can redefine free()
using the following macro:
#define free(p) PlgMemFree(p)