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:

`PLGFWMEM_ALLOC_FAIL_NULL`	If the allocation fails, return `NULL.` This flag should always be set.
`PLGFWMEM_INIT_ZEROED`	Initialize allocated memory with zeros.
`PLGFWMEM_INIT_UNSPECIFIED`	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:

TEXT

    #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)