mexhost

Create host process for C++ MEX function

Syntax

mh = mexhost

mh = mexhost("EnvironmentVariables",envVariables)

Description

mh = mexhost creates a MEX host process that is used to run C++ MEX functions. The default process name is MATLABMexHost.

Use the feval method of the matlab.mex.MexHost object returned to execute C++ MEX functions in the MEX host process.

mh = mexhost("EnvironmentVariables",envVariables) sets environment variable with values defined in envVariables for the process.

Examples

Run C++ MEX Function Out of Process

Create a host process and run a C++ MEX function in that process.

The arrayProduct.cpp C++ MEX file contains the source code for a function that multiplies an array by a scalar input and returns the resulting array. Open this file and save it on your MATLAB^® path. Build the C++ MEX source file using the mex command. To set up the MEX build, follow the instructions in Build C++ MEX Programs.

mex arrayProduct.cpp

Create a host process. The mexhost function returns a matlab.mex.MexHost object.

mh = mexhost;

Use the feval method of the matlab.mex.MexHost object to evaluate the C++ MEX function in the host process.

result = feval(mh,"arrayProduct",10,[2,4,6,8])

result =

    20    40    60    80

Find Process ID

You can use the MexHost object to find the identifier of the process created by the mexhost function.

mh = mexhost;
mh.ProcessIdentifier

ans = 
    "13336"

Each call to mexhost creates a process.

Set Environment Variable for Library

Set the value of environment variable envName1 to envVal1 and the value of variable envName2 to envVal2.

s = ["envName1","envVal1"
     "envName2","envVal2"];
mh = mexhost("EnvironmentVariables",s)

mh = 

  MexHost with properties:

             ProcessName: "MATLABMexHost"
       ProcessIdentifier: "19344"
               Functions: [0×0 string]
    EnvironmentVariables: "envName1"    "envVal1"
                          "envName2"    "envVal2"

Input Arguments

envVariables — Environment variables and values

n-by-2 string array

Environment variables and values, specified as an n-by-2 string array. Non-ASCII characters are not supported. The first column is the name of the environment variable and the second column is the value.

The function prepends the environment value to the environment variable if the variable name is:

• PATH on Windows^® platforms

• LD_LIBRARY_PATH on Linux^® platforms

• DYLD_LIBRARY_PATH on macOS platforms

Example: mh = mexhost("EnvironmentVariables",["path","c:\bin\mylib\"])

Output Arguments

mh — Host process

matlab.mex.MexHost object

Host process, returned as a matlab.mex.MexHost object. Use this process to run a C++ MEX function outside of the MATLAB process.

More About

Process Life Cycle

MATLAB terminates the process when the object returned by mexhost is destroyed. MATLAB destroys the object when any of the following occur.

• The MEX host variable returned by mexhost goes out of scope, causing MATLAB to destroy the object.

• The delete method is called on the MEX host variable explicitly.

• The clear function is called on the MEX host variable and there are no other references to the object.

• The clear function is called with any of these options: clear java, clear classes, or clear all.

Unload C++ MEX Functions

To unload all C++ MEX functions from their host processes, call clear mex or clear functions. To unload a specific C++ MEX function all host processes running it, call clear on the function name. For more information, see the clear function and Out-of-Process Execution of C++ MEX Functions.

Version History

Introduced in R2019a