clibConfiguration

Change execution mode of C++ library interface

Since R2023a

Syntax

libraryconfig = clibConfiguration(libname)

libraryconfig = clibConfiguration(libname,ExecutionMode=ExecutionMode)

Description

MATLAB^® can load an interface to a C++ library either in-process or out-of-process. Use clibConfiguration to change the execution mode.

libraryconfig = clibConfiguration(libname) returns configuration object CLibraryConfiguration for interface to C++ library libname.

libraryconfig = clibConfiguration(libname,ExecutionMode=ExecutionMode) changes the execution mode of the library. Use ExecutionMode to indicate whether MATLAB loads the C++ library interface in-process or out-of-process. The setting is persistent across different MATLAB sessions.

MATLAB loads the library when you call your library using the syntax clib.libraryName followed by the library construct type. If the ExecutionMode is "inprocess", then you cannot change the interface to the library and reload it into MATLAB. To enable making changes to the interface and reloading in the same session, restart MATLAB, and then call clibConfiguration(ExecutionMode="outofprocess").

Examples

Display Configuration for Library

Suppose that you built an interface libnameInterface.dll in C:\work which is on the MATLAB path for a library libname.lib. Assuming that the library is not loaded, type:

configObj = clibConfiguration("libname")

configObj =
      CLibraryConfiguration for libname with properties:
        InterfaceLibraryPath: "C:\work"
                   Libraries: "libname.lib"
                      Loaded: 0
               ExecutionMode: inprocess

Change Execution Mode

Suppose that you built an interface mylibInterface.dll in C:\work which is on MATLAB path for a library mylib.lib. To change the execution mode if the library is not loaded, type:

configObj = clibConfiguration("mylib",ExecutionMode="outofprocess")

configObj =
      CLibraryConfiguration for mylib with properties:
        InterfaceLibraryPath: "C:\work"
                   Libraries: "mylib.lib"
                      Loaded: 0
               ExecutionMode: outofprocess

Input Arguments

libname — Name of interface to C++ library

string | character vector

Name of the interface to a C++ library, specified as a string or a character vector.

ExecutionMode — Execution mode

"inprocess" (default) | "outofprocess"

Execution mode indicating whether to load the library in the same process as MATLAB, specified as "inprocess" or "outofprocess". The default "inprocess" loads the library in the MATLAB process. Use this mode for performance-critical use cases. Set this mode after you develop and test the interface.

Select "outofprocess" for:

• Testing the interface library, which requires rebuilding the interface in MATLAB.

• If your C++ library requires a 3rd party library which is also shipped with MATLAB, but you need a different version of the library, then set execution mode to "outofprocess" before you use or distribute the interface.

Version History

Introduced in R2023a