MATLAB Compiler

Functions Generated from M-Files

For each M-file specified on the MATLAB Compiler command line, the Compiler generates two functions, the mlx function and the mlf function. Each of these generated functions performs the same action (calls your M-file function). The two functions have different names and present different interfaces. The name of each function is based on the name of the first function in the M-file (sierpinski, in this example); each function begins with a different three-letter prefix.

mlx Interface Function

The function that begins with the prefix mlx takes the same type and number of arguments as a MATLAB MEX-function. (See the External Interfaces documentation for more details on MEX-functions). The first argument, nlhs, is the number of output arguments, and the second argument, plhs, is a pointer to an array that the function will fill with the requested number of return values. (The "lhs" in these argument names is short for "left-hand side" -- the output variables in a MATLAB expression are those on the left-hand side of the assignment operator.) The third and forth parameters are the number of inputs and an array containing the input variables.

• void mlxSierpinski(int nlhs, mxArray *plhs[], int nrhs,
                     mxArray *prhs[])
  

mlf Interface Function

The second of the generated functions begins with the prefix mlf. This function expects its input and output arguments to be passed in as individual variables rather than packed into arrays. If the function is capable of producing one or more outputs, the first argument is the number of outputs requested by the caller.

• void mlfSierpinski(int nargout, mxArray** x, mxArray** y,               
                     mxArray* iterations, mxArray* draw)
  

Note that in both cases, the generated functions allocate memory for their return values. If you do not delete this memory (via mxDestroyArray) when you are done with the output variables, your program will leak memory.

Your program may call whichever of these functions is more convenient, as they both invoke your M-file function in an identical fashion. Most programs will likely call the mlf form of the function to avoid managing the extra arrays required by the mlx form. The example program in triangle.c calls mlfSierpinski.

• mlfSierpinski(2, &x, &y, iterations, draw);
  

In this call, the caller requests two output arguments, x and y, and provides two inputs, iterations and draw.

If the output variables you pass in to an mlf function are nonNULL, the mlf function will attempt to free them using mxDestroyArray. This means that you can reuse output variables in consecutive calls to mlf functions without worrying about memory leaks. It also implies that you must pass either NULL or a valid MATLAB array for all output variables or your program will fail because the memory manager cannot distinguish between a noninitialized (invalid) array pointer and a valid array. It will try to free a pointer that is not NULL -- freeing an invalid pointer usually causes a segmentation fault or similar fatal error).

Using varargin and varargout in an M-Function Interface

If your M-function interface uses varargin or varargout, you must pass them as cell arrays. For example, if you have N varargins, you need to create one cell array of size 1-by-N. Similarly, varargouts are returned back as one cell array. The length of the varargout is equal to the number of return values specified function call minus the number of actual variables passed. As in MATLAB, the cell array representing varagout has to be the last return variable (the variable preceding the first input variable) and the cell array representing varargins has to be the last formal parameter to the function call.

For information on creating cell arrays, refer to the C MX-function interface in the External Interfaces documentation.

For example, consider this M-file interface.

• [a,b,varargout] = myfun(x,y,z,varargin)
  

The corresponding C interface for this is

• void mlfMyfun(int numOfRetVars, mxArray **a, mxArray **b, 
                mxArray **varargout, mxArray *x, mxArray *y,
                mxArray *z, mxArray *varargin)
  

In this example, the number of elements in varargout is (numOfRetVars - 2), where 2 represents the two actual variables, a and b, being returned. Both varargin and varargout are single row, multiple column cell arrays.

Print and Error Handling Functions

Reference

© 1994-2005 The MathWorks, Inc.