MATLAB®

Advanced Topics

Help Files

Because the MATLAB interpreter chooses the binary MEX-file when both an M-file and a MEX-file with the same name are encountered in the same directory, it is possible to use M-files for documenting the behavior of your binary MEX-files. The help command automatically finds and displays the appropriate M-file when help is requested and the interpreter finds and executes the corresponding binary MEX-file when the function is invoked.

Back to Top

Linking Multiple Files

You can combine multiple source files, object files, and file libraries to build a binary MEX-file. To do this, list the additional files, with their file extensions, separated by spaces. The name of the resulting MEX-file is the name of the first file in the list.

The following command combines multiple files of different types into a binary MEX-file called circle.ext, where ext is the extension corresponding to the current platform:

mex circle.F square.o rectangle.F shapes.o

You may find it useful to use a software development tool like MAKE to manage MEX-file projects involving multiple source files. Simply create a MAKEFILE that contains a rule for producing object files from each of your source files, and then invoke the mex build script to combine your object files into a binary MEX-file. This way you can ensure that your source files are recompiled only when necessary.

Note    On Linux[1] systems, you must use the -fortran switch to the mex script if you are linking Fortran objects.

Back to Top

Workspace for MEX-File Functions

Unlike M-file functions, MEX-file functions (binary MEX-files) do not have their own variable workspace. MEX-file functions operate in the caller's workspace. mexEvalString evaluates the string in the caller's workspace. In addition, you can use the mexGetVariable and mexPutVariable routines to get and put variables into the caller's workspace.

Back to Top

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 in the Programming Fundamentals documentation. Memory management within source MEX-files can have special considerations, as described in Memory Management.

Using the 64-Bit API

To work with a 64-bit mxArray, your source code must comply with the 64-bit API, which consists of the functions in the following table.

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

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 size_t in C or INTEGER*8 in Fortran. These types are unsigned, unlike int and INTEGER*4, which are the types 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 or INTEGER*4 values to mwSize or mwIndex; the returned value can not 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), 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 or INTEGER*4 in Fortran. Be careful to avoid assigning a large mwSize or mwIndex value to an int, INTEGER*4, or other variable that might be too small.

Back to Top

Memory Management

When a binary MEX-file returns control to MATLAB, it returns the results of its computations in the output arguments—the mxArrays contained in the left-hand side arguments plhs[]. MATLAB destroys any mxArray created by the MEX-file that is not in this argument list. In addition, MATLAB frees any memory that was allocated in the MEX-file using the mxCalloc, mxMalloc, or mxRealloc functions.

Consequently, any misconstructed arrays left over at the end of a binary MEX-file's execution have the potential to cause memory errors.

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. For additional information on memory management techniques, see the sections Memory Management in Creating C Language MEX-Files and Memory Management Issues.

^[1] Linux is a registered trademark of Linus Torvalds.

Back to Top

Examples of Fortran Source MEX-Files

Debugging Fortran Source MEX-Files