mxMalloc (C and Fortran) - Allocate uninitialized dynamic memory using MATLAB memory manager - MATLAB (original) (raw)

Allocate uninitialized dynamic memory using MATLAB memory manager

C Syntax

#include "matrix.h" #include <stdlib.h> void *mxMalloc(mwSize n);

Fortran Syntax

#include "fintrf.h" mwPointer mxMalloc(n) mwSize n

Arguments

n

Number of bytes to allocate for n greater than0

Returns

Pointer to the start of the allocated dynamic memory, if successful. If unsuccessful in a MAT or engine standalone application, then mxMalloc returnsNULL in C (0 in Fortran). If unsuccessful in a MEX file, then the MEX file terminates and control returns to the MATLAB® prompt.

mxMalloc is unsuccessful when there is insufficient free heap space.

If you call mxMalloc in C with value n =0, then MATLAB returns either NULL or a valid pointer.

Description

mxMalloc allocates contiguous heap space sufficient to holdn bytes. To allocate memory in MATLAB applications, use mxMalloc instead of the ANSI® C malloc function.

In MEX files, but not MAT or engine applications, mxMalloc registers the allocated memory with the MATLAB memory manager. When control returns to the MATLAB prompt, the memory manager then automatically frees, or_deallocates_, this memory.

How you manage the memory created by this function depends on the purpose of the data assigned to it. If you assign it to an output argument in plhs[] using a function such as mxSetDoubles, then MATLAB is responsible for freeing the memory.

If you use the data internally, then the MATLAB memory manager maintains a list of all memory allocated by the function and automatically frees (deallocates) the memory when control returns to the MATLAB prompt. In general, we recommend that MEX file functions destroy their own temporary arrays and free their own dynamically allocated memory. It is more efficient to perform this cleanup in the source MEX file than to rely on the automatic mechanism. Therefore, when you finish using the memory allocated by this function, callmxFree to deallocate the memory.

If you do not assign this data to an output argument, and you want it to persist after the MEX file completes, then call mexMakeMemoryPersistent after calling this function. If you write a MEX file with persistent memory, then be sure to register amexAtExit function to free allocated memory in the event your MEX file is cleared.

Version History

Introduced before R2006a