Older Newer
Fri, 13 Jun 2008 07:22:33 . . . . afh [new page]


Changes by last author:

Added:
= 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.

<code>

</code>

: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 ==

<code>

if (set_array_mode(1)) {

Info("Using host application buffer allocation API.");

}

else {

Warn("Unable to use host buffer allocation. Using malloc/free instead.");

}

</code>

== 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.