mxFree (External Interfaces Reference)

Free dynamic memory allocated by mxCalloc

C Syntax

#include "matrix.h"
void mxFree(void *ptr);

Arguments

ptr
Pointer to the beginning of any memory parcel allocated by mxCalloc.

Description

To deallocate heap space, MATLAB applications should always call mxFree rather than the ANSI C free function.

mxFree works differently in MEX-files than in stand-alone MATLAB applications.

In MEX-files, mxFree automatically

Calls the ANSI C free function, which deallocates the contiguous heap space that begins at address ptr.

Removes this memory parcel from the MATLAB memory management facility's list of memory parcels.

The MATLAB memory management facility maintains a list of all memory allocated by mxCalloc (and by the mxCreate calls). The MATLAB memory management facility automatically frees (deallocates) all of a MEX-file's parcels when control returns to the MATLAB prompt.

When mxFree appears in stand-alone MATLAB applications, mxFree simply calls the ANSI C free function.

In a MEX-file, your use of mxFree depends on whether the specified memory parcel is persistent or nonpersistent. By default, memory parcels created by mxCalloc are nonpersistent. However, if an application calls mexMakeMemoryPersistent, then the specified memory parcel becomes persistent.

The MATLAB memory management facility automatically frees all nonpersistent memory whenever a MEX-file completes. Thus, even if you do not call mxFree, MATLAB takes care of freeing the memory for you. Nevertheless, it is a good programming practice to deallocate memory just as soon as you are through using it. Doing so generally makes the entire system run more efficiently.

When a MEX-file completes, the MATLAB memory management facility does not free persistent memory parcels. Therefore, the only way to free a persistent memory parcel is to call mxFree. Typically, MEX-files call mexAtExit to register a clean-up handler. Then, the clean-up handler calls mxFree.

Examples

See mxcalcsinglesubscript.c in the mx subdirectory of the examples directory.

For additional examples, see phonebook.c in the refbook subdirectory of the examples directory; see explore.c and mexatexit.c in the mex subdirectory of the examples directory; see mxcreatecharmatrixfromstr.c, mxisfinite.c, mxmalloc.c, and mxsetdimensions.c in the mx subdirectory of the examples directory.

mxDuplicateArray mxFreeMatrix (Obsolete)