mxFree (C and Fortran)

Free dynamic memory allocated by mxCalloc, mxMalloc, mxRealloc, mxArrayToString, or mxArrayToUTF8String functions

C Syntax

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

Fortran Syntax

#include "fintrf.h"
subroutine mxFree(ptr)
mwPointer ptr

Arguments

ptr: Pointer to the beginning of any memory parcel allocated by mxCalloc, mxMalloc, or mxRealloc. If ptr is a NULL pointer, the function does nothing.

Description

mxFree deallocates heap space using the MATLAB^® memory management facility. This function ensures correct memory management in error and abort (Ctrl+C) conditions.

To deallocate heap space in C MATLAB applications, call mxFree instead of the ANSI^® C free function.

In MEX files, but excluding MAT or engine standalone applications, the MATLAB memory management facility maintains a list of all memory allocated by the following functions:

mxCalloc
mxMalloc
mxRealloc
mxArrayToString
mxArrayToUTF8String

The memory management facility automatically deallocates all parcels managed by a MEX file when the MEX file completes and control returns to the MATLAB prompt. mxFree also removes the memory parcel from the memory management list of parcels.

When mxFree appears in a MAT or engine standalone MATLAB application, it simply deallocates the contiguous heap space that begins at address ptr.

In MEX files, your use of mxFree depends on whether the specified memory parcel is persistent or nonpersistent. By default, memory parcels created by mxCalloc, mxMalloc, mxRealloc, mxArrayToString, and mxArrayToUTF8String are nonpersistent. The 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 good programming practice to deallocate memory when you are through using it. Doing so generally makes the entire system run more efficiently.

If an application calls mexMakeMemoryPersistent, the specified memory parcel becomes persistent. When a MEX file completes, the 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 cleanup handler. The cleanup handler calls mxFree.

Do not use mxFree for an mxArray created by any other functions in the Matrix Library API. Use mxDestroyArray instead.