How to Run Out of Process

Follow these steps to run your C++ MEX function out of process:

When running out of process, C++ MEX functions always execute in the same folder as the MATLAB current folder. Changing the MATLAB current folder after creating the MEX host object results in the same change in the C++ MEX function context.

Running arrayProduct MEX Function Out of Process

The following example runs the arrayProduct C++ MEX function out-of-process. The C++ MEX source code is available in the file arrayProduct.cpp. To use this example C++ MEX function, open the arrayProduct.cpp source file, save it on your MATLAB path, and build the C++ MEX function using the instructions in Build C++ MEX Programs.

After building the C++ MEX function, start the MEX host process using the mexhost function. This function returns an object of the matlab.mex.MexHost class.

Use the feval method to run the arrayProduct C++ MEX function in the host process. Pass the C++ MEX functions name and arguments to feval. Return the results to MATLAB by assigning the output of feval.

mh = mexhost;
result = feval(mh,'arrayProduct',2,[1 2 3 4])

result =
     2     4     6     8

Run arrayProduct in another MEX host process. First create the MEX host process by calling mexhost again and assigning the output to a different variable. Then call feval on the new host.

mh2 = mexhost;
result2 = feval(mh2,'arrayProduct',2,rand(1,10));

You can run other C++ MEX functions in the same process using the same matlab.mex.MexHost object returned by mexhost.

result2 = feval(mh2,'anotherMexFunction',inputs);

Process Lifecycle

The MEX host process lifecycle is coupled to the lifecycle of the matlab.mex.MexHost object returned by mexhost. Like any handle object, MATLAB invokes the delete method when the object is no longer referenced anywhere. If MATLAB invokes delete or if you call delete on the object explicitly, MATLAB ends the process associated with the MexHost object.

You can end the process explicitly by calling the clear function with any of these options:

Getting Information About the MEX Host Process

Use the matlab.mex.MexHost object to get information about the MEX host process. These properties provide information about the process and loaded functions.

For more information on these properties, see matlab.mex.MexHost.

Always Run Out of Process

In certain cases, you might always want to run your C++ MEX function out-of-process. For example, running out of process can be necessary if there are third-party library conflicts between MATLAB and the C++ MEX function.

To provide a convenient way to run the C++ MEX function out of process, create a wrapper MATLAB function. The wrapper function creates the MEX host object and runs the C++ MEX function in that process.

For example, suppose that you want to create a wrapper function for the arrayProduct.cpp C++ MEX function that is included in the documentation as an example. Create a MATLAB function with the name arrayProduct.m and put this file in a folder that is on the MATLAB path. Build the C++ MEX function and assign a different name for the compiled MEX file.

The wrapper function creates a matlab.mex.MexHost object that is assigned to a persistent variable so that the process is not destroyed between subsequent calls to the wrapper function. The function uses this object to call the feval method for out-of-process execution of the C++ MEX function. If the MEX host object is not valid, then the function creates a MEX host process.

function result = arrayProduct(scalefactor,inputarray)
    persistent mh
    if ~(isa(mh,'matlab.mex.MexHost') && isvalid(mh))
        mh = mexhost;
    end
    result = feval(mh,"arrayProductMEX",scalefactor,inputarray);
end

To build the C++ MEX function, open the arrayProduct.cpp source file and save it on your MATLAB path. Build the C++ MEX function using the instructions in this topic, Build C++ MEX Programs.

The following command builds MEX file with the root name arrayProductMEX and puts it in the folder with the wrapper function, which is assumed to be MyPathFolder in this example. The mex command creates the folder if it does not exist.

mex -output arrayProductMEX -outdir MyPathFolder arrayProduct.cpp

To use the C++ MEX function, call it from the command line like any function via the wrapper function.

result = arrayProduct(2,[1 2 3 4]);
result

result =

     2     4     6     8

The following code calls the C++ MEX function in a for loop. The first call to arrayProduct creates the MEX host process. Subsequent calls use the same process unless the process is destroyed by, for example, a crash of the C++ MEX function.

for k = 1:5
   results(k,:) = arrayProduct(k,[1 2 3 4]);
end
results

results =
     1     2     3     4
     2     4     6     8
     3     6     9    12
     4     8    12    16
     5    10    15    20

To destroy the MEX host process, clear all functions that define the MEX host process variable (mh in this example) as persistent. In this example, clear the arrayProduct.m function.

clear arrayProduct.m

Calling clear functions causes the destruction of the matlab.mex.MexHost object that is stored in the persistent variable and therefore terminates the MEX host process.

Debugging Out-of-Process MEX Functions

You can attach a C++ debugger to your C++ MEX function and set break points to debug your program. Here are the steps to set up and debug a C++ MEX function out of process.

For information on using specific debuggers, see the documentation for those debuggers.