mex command uses the
by default. This topic describes how to upgrade your MEX files to
use the 64-bit API.
You can continue to use the 32-bit API by calling the
-compatibleArrayDims option. However,
for more information about using this option, see What If I Do Not Upgrade?.
To review and update MEX file source code, use the following checklist.
Prepare your code before editing — see Back Up Files and Create Tests.
Iteratively change and test code.
Before building your MEX files with the 64-bit API, refactor your existing code by checking for the following conditions:
After each change, build and test your code:
Build with the 32-bit API. For example, to build
mex -compatibleArrayDims myMexFile.c
Test after each refactoring — see Test, Debug, and Resolve Differences After Each Refactoring Iteration.
Compile using the 64-bit API. To build
Resolve failures and warnings — see Resolve -largeArrayDims Build Failures and Warnings.
Compare Results — see Execute 64-Bit MEX File and Compare Results with 32-Bit Version.
Check memory — see Experiment with Large Arrays.
The following procedures use C/C++ terminology and example code. Fortran MEX files share the same issues, with more tasks described in Additional Steps to Update Fortran Source Code.
Before modifying your code, verify that the MEX file works with the 32-bit API. At a minimum, build a list of expected inputs and outputs, or create a full test suite. Use these tests to compare the results with the updated source code. The results should be identical.
Back up all source, binary, and test files.
To handle large arrays, convert variables containing array indices
or sizes to use the
instead of the 32-bit
int type. Review your code
to see if it contains the following types of variables:
Variables used directly by the MX Matrix Library functions — see Update Arguments Used to Call Functions in the 64-Bit API.
Intermediate variables — see Update Variables Used for Array Indices and Sizes.
Variables used as both size/index values and as 32-bit integers — see Analyze Other Variables.
Identify the 64-bit API functions in your code that use the
For the list of functions, see Using the 64-Bit API. Search for the variables that you use
to call the functions. Check the function signature, shown under the Syntax heading on the function reference documentation.
The signature identifies the variables that take
as input or output values. Change your variables to use the correct
For example, suppose that your code uses the
as shown in the following statements:
int nrows,ncolumns; ... y_out = mxCreateDoubleMatrix(nrows, ncolumns, mxREAL);
To see the function signature, type:
The signature is:
mxArray *mxCreateDoubleMatrix(mwSize m, mwSize n, mxComplexity ComplexFlag)
The type for input arguments
Change your code as shown in the table.
If your code uses intermediate variables to calculate size and
index values, use
these variables. For example, the following code declares the inputs
mxCreateDoubleMatrix as type
mwSize nrows,ncolumns; /* inputs to mxCreateDoubleMatrix */ int numDataPoints; nrows = 3; numDataPoints = nrows * 2; ncolumns = numDataPoints + 1; ... y_out = mxCreateDoubleMatrix(nrows, ncolumns, mxREAL);
This example uses the intermediate variable, numDataPoints (of
int), to calculate the value of ncolumns.
If you copy a 64-bit value from nrows into the
32-bit variable, numDataPoints, the resulting value
truncates. Your MEX file could crash or produce incorrect results.
mwSize for numDataPoints,
as shown in the following table.
You do not need to change every integer variable in your code.
For example, field numbers in structures and status codes are of type
However, you need to identify variables used for multiple purposes
and, if necessary, replace them with multiple variables.
The following example creates a matrix, myNumeric, and a structure, myStruct, based on the number of sensors. The code uses one variable, numSensors, for both the size of the array and the number of fields in the structure.
mxArray *myNumeric, *myStruct; int numSensors; mwSize m, n; char **fieldnames; ... myNumeric = mxCreateDoubleMatrix(numSensors, n, mxREAL); myStruct = mxCreateStructMatrix(m, n, numSensors, fieldnames);
The function signatures for
mxArray *mxCreateDoubleMatrix(mwSize m, mwSize n, mxComplexity ComplexFlag) mxArray *mxCreateStructMatrix(mwSize m, mwSize n, int nfields, const char **fieldnames);
your code uses numSensors for the variable m.
The type for m is
mxCreateStructMatrix function, your code
uses numSensors for the variable nfields.
The type for nfields is
Replace numSensors with two new variables to handle
both functions, as shown in the following table.
/* create 2 variables */ /* of different types */ mwSize numSensorSize; int numSensorFields;
myNumeric = mxCreateDoubleMatrix( numSensors, n, mxREAL);
/* use mwSize variable */ /* numSensorSize */ myNumeric = mxCreateDoubleMatrix( numSensorSize, n, mxREAL);
myStruct = mxCreateStructMatrix( m, n, numSensors, fieldnames);
/* use int variable */ /* numSensorFields */ myStruct = mxCreateStructMatrix( m, n, numSensorFields, fieldnames);
While updating older MEX files, you could find calls to unsupported
functions, such as
mxIsString. MATLAB® removed support for
these functions in Version 7.1 (R14SP3). You cannot use unsupported
functions with 64-bit array dimensions. For the list of unsupported
functions and the recommended replacements, see Obsolete Functions No Longer Documented.
Update your code to use an equivalent function, if available.
For example, use
myMexFile.c with the 32-bit API,
mex -compatibleArrayDims myMexFile.c
Use the tests you created at the beginning of this process to compare the results of your updated MEX file with your original binary file. Both MEX files should return identical results. If not, debug and resolve any differences. Differences are easier to resolve now than when you build using the 64-bit API.
After reviewing and updating your code, compile your MEX file
using the large array handling API. To build
the 64-bit API, type:
are MATLAB types, your compiler sometimes refers to them as
or by other similar names.
Most build problems are related to type mismatches between 32-bit and 64-bit types. Refer to Step 5 in How do I update MEX-files to use the large array handling API (-largeArrayDims)? to identify common build problems for specific compilers, and possible solutions.
Compare the results of running your MEX file compiled with the 64-bit API with the results from your original binary. If there are any differences or failures, use a debugger to investigate the cause. For information on the capabilities of your debugger, refer to your compiler documentation.
To identify issues—and possible solutions—you might encounter when running your MEX files, refer to Step 6 in How do I update MEX-files to use the large array handling API (-largeArrayDims)?.
After you resolve issues and upgrade your MEX file, it replicates the functionality of your original code while using the large array handling API.
If you have access to a machine with large amounts of memory, you can experiment with large arrays. An array of double-precision floating- point numbers (the default in MATLAB) with 232 elements takes approximately 32 GB of memory.
For an example that demonstrates the use of large arrays, see
arraySize.c MEX file in Handling Large mxArrays.