set_array_mode

Syntax

bool set_array_mode (int mode)

Arguments

mode
Determines the default Array allocation mode. Set it to 1 to allocate Arrays using the host application's buffer allocation API, if any (this is the default). Set it to 0 to allocate Arrays from the C runtime heap (this is the fallback case).

Return

Returns true if the requested allocation mode was set, or false if the request could not be honored (e.g., if the host application does not support the buffer allocation API). In the latter case, FM falls back to case 0 (using malloc and free).

Description

If the host application provides a buffer allocation API, it is usually more effective to use this API instead of the basic C runtime heap allocation API, since the host application is able to coordinate FM's buffer allocation requests with its own memory allocation needs.

If FM allocates Arrays from the C runtime heap, either because the host application provides no buffer allocation API or because the filter calls set_array_mode(0), then be aware that FM may fail to allocate an Array, even if the host application has allocated more memory to itself than is necessary.

Example

    if (set_array_mode(1)) {
        Info("Using host application buffer allocation API.");
    }
    else {
        Warn("Unable to use host buffer allocation. Using malloc/free instead.");
    }

Also see

allocArray, allocArrayPad, freeArray, getArray, putArray, copyArray, malloc, free

Comments

Everyone can add his comments about his experiences with this function here. Tips for using it are welcome, too.