Handling Large mxArrays

Binary MEX-files built on 64-bit platforms can handle 64-bit mxArrays. These large data arrays can have up to 2⁴⁸–1 elements. The maximum number of elements a sparse mxArray can have is 2⁴⁸-2.

Using the following instructions creates platform-independent binary MEX-files as well.

Your system configuration can impact the performance of MATLAB. The 64-bit processor requirement enables you to create the mxArray and access data in it. However, your system's memory, in particular the size of RAM and virtual memory, determine the speed at which MATLAB processes the mxArray. The more memory available, the faster the processing.

The amount of RAM also limits the amount of data you can process at one time in MATLAB. For guidance on memory issues, see Strategies for Efficient Use of Memory. Memory management within source MEX-files can have special considerations, as described in Memory Management.

Using the 64-Bit API

The signatures of the API functions shown in the following table use the mwSize or mwIndex types to work with a 64-bit mxArray. The variables you use in your source code to call these functions must be the correct type.

mxArray Functions Using mwSize/mwIndex

¹Fortran function only

²C function only

Functions in this API use the mwIndex and mwSize types. For information about using these macros, see Required Header Files.

Back to Top

Building the Binary MEX-File

Use the mex build script option -largeArrayDims with the 64-bit API.

Back to Top

Example

The example, arraySize.c in matlabroot/extern/examples/mex, illustrates memory requirements of large mxArrays. To see the example, open the file in MATLAB Editor.

This function requires one positive scalar numeric input, which it uses to create a square matrix. It checks the size of the input to make sure your system can theoretically create a matrix of this size. If the input is valid, it displays the size of the mxArray in kilobytes.

To build this MEX-file, type:

mex -largeArrayDims arraySize.c

To run the MEX-file, type:

arraySize(2^10)

If your system has enough available memory, MATLAB displays:

Dimensions: 1024 x 1024
Size of array in kilobytes: 1024

If your system does not have enough memory to create the array, MATLAB displays an Out of memory error.

You can experiment with this function to test the performance and limits of handling large arrays on your system.

Back to Top

Caution Using Negative Values

When using the 64-bit API, mwSize and mwIndex are equivalent to size_t in C/C++. This type is unsigned, unlike int, which is the type used in the 32-bit API. Be careful not to pass any negative values to functions that take mwSize or mwIndex arguments. Do not cast negative int values to mwSize or mwIndex; the returned value cannot be predicted. Instead, change your code to avoid using negative values.

Back to Top

Building Cross-Platform Applications

If you develop cross-platform applications (programs that can run on both 32- and 64-bit architectures), you must pay attention to the upper limit of values you use for mwSize and mwIndex. The 32-bit application reads these values and assigns them to variables declared as int in C/C++. Be careful to avoid assigning a large mwSize or mwIndex value to an int or other variable that might be too small.

Back to Top

Debugging C/C++ Language MEX-Files

Memory Management

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit