Learn more about MATLAB

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

C Syntax

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

Fortran Syntax

mwPointer mxMalloc(n)
mwSize n

Arguments

n: Number of bytes to allocate

Returns

Pointer to the start of the allocated dynamic memory, if successful. If unsuccessful in a stand alone (non-MEX-file) application, mxMalloc returns NULL in C (0 in Fortran). If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt.

mxMalloc is unsuccessful when there is insufficient free heap space.

Description

MATLAB applications should always call mxMalloc rather than the ANSI C malloc function to allocate memory. In stand alone applications, such as the MATLAB engine, mxMalloc calls the malloc function. In MEX-files, mxMalloc automatically:

Allocates enough contiguous heap space to hold n bytes.
Registers the returned heap space with the MATLAB memory manager.

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 the mxSetPr function, MATLAB is responsible for freeing the memory.

If you use the data internally, 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, call mxFree 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, call mexMakeMemoryPersistent after calling this function. If you write a MEX-file with persistent memory, be sure to register a mexAtExit function to free allocated memory in the event your MEX-file is cleared.

C Examples

See mxmalloc.c and mxsetdimensions.c in the matlabroot/extern/examples/mx folder .