Handling Large mxArrays

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

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

Your system configuration can affect the performance of MATLAB®. The 64-bit processor requirement enables you to create the mxArray and access data in it. However, the system 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

mxCalcSingleSubscript

mxCreateSparseLogicalMatrix 2

mxCallocmxCreateStructArray

mxCopyCharacterToPtr1

mxCreateStructMatrix

mxCopyComplex16ToPtr1

mxGetCell

mxCopyComplex8ToPtr1

mxGetDimensions

mxCopyInteger1ToPtr1

mxGetElementSize

mxCopyInteger2ToPtr1

mxGetField

mxCopyInteger4ToPtr1

mxGetFieldByNumber

mxCopyPtrToCharacter1

mxGetIr

mxCopyPtrToComplex161

mxGetJc

mxCopyPtrToComplex81

mxGetM

mxCopyPtrToInteger11

mxGetN

mxCopyPtrToInteger21

mxGetNumberOfDimensions

mxCopyPtrToInteger41

mxGetNumberOfElements

mxCopyPtrToPtrArray1

mxGetNzmax

mxCopyPtrToReal41

mxGetProperty

mxCopyPtrToReal81

mxGetString

mxCopyReal4ToPtr1

mxMalloc

mxCopyReal8ToPtr1

mxRealloc
mxCreateCellArraymxSetCell
mxCreateCellMatrixmxSetDimensions
mxCreateCharArraymxSetField
mxCreateCharMatrixFromStringsmxSetFieldByNumber
mxCreateDoubleMatrixmxSetIr

mxCreateLogicalArray2

mxSetJc

mxCreateLogicalMatrix2

mxSetM
mxCreateNumericArraymxSetN
mxCreateNumericMatrixmxSetNzmax
mxCreateSparsemxSetProperty

1Fortran function only.

2C function only.

Functions in this API use the mwIndex, mwSize, and mwPointer preprocessor macros.

Building the Binary MEX-File

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

Caution Using Negative Values

When using the 64-bit API, mwSize and mwIndex are equivalent to INTEGER*8 in Fortran. This type is unsigned, unlike INTEGER*4, 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 INTEGER*4 values to mwSize or mwIndex; the returned value cannot be predicted. Instead, change your code to avoid using negative values.

Building Cross-Platform Applications

If you develop cross-platform applications (programs that can run on both 32- and 64-bit architectures), 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 INTEGER*4 in Fortran. Be careful to avoid assigning a large mwSize or mwIndex value to an INTEGER*4 or other variable that might be too small.

Was this topic helpful?