Load C++ Library In-Process or Out-of-Process

Load In-Process C++ Library

MATLAB® can load an interface to a C++ library either in-process or out-of-process. By default, when you call a command in the clib namespace, MATLAB loads the library in-process. In other words, MATLAB loads the library in the same process as MATLAB. Use this mode for performance-critical use cases.

Load Out-of-Process C++ Library

MATLAB can run C++ functions in a separate process using out-of-process execution mode. Running in a separate process enables you to:

  • Use some third-party libraries that conflict with MATLAB. For example, your C++ library might require a third-party library that is also shipped with MATLAB, but the C++ library requires a different version of the third-party library.

  • Efficiently iterate on the development of an interface, by eliminating the need to restart MATLAB while testing.

  • Isolate the MATLAB process from crashes in the C++ library code.

  • Interrupt C++ library interface execution by pressing Ctrl+C. (since R2025a)

To run out-of-process, in your workflow script created by the clibPublishInterfaceWorkflow function, run the Enable out-of-process execution mode section described in Publish with Workflow Script.

Alternatively, from the command line, call the clibConfiguration function with the ExecutionMode name-value argument set to "outofprocess".

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

libraryconfig =

      CLibraryConfiguration for mylib with properties:

                 InterfaceLibraryPath: "C:\work"
                            Libraries: ""
                               Loaded: 0
                        ExecutionMode: outofprocess
     OutOfProcessEnvironmentVariables: dictionary (string-->string) with no entries

Once the library interface is configured to run out-of-process, when you call a clib command in the library namespace, MATLAB loads the library out-of-process.

Unload Out-of-Process C++ Library

If you run the Enable out-of-process execution mode section in the workflow script created by the clibPublishInterfaceWorkflow function, then you can unload the C++ library by running the Unload out-of-process library section.

Alternatively, call unload on the MATLAB interface. For example, suppose that you built an interface schoolInterface.dll to the school C++ library and the interface is loaded and set to out-of-process execution. Display the library interface configuration.

libraryconfig = clibConfiguration("school")
libraryconfig = 
  CLibraryConfiguration for school with properties:
            InterfaceLibraryPath: "C:\work"
                       Libraries: ""
                          Loaded: 1
                   ExecutionMode: outofprocess
                       ProcessID: 12345
OutOfProcessEnvironmentVariables: dictionary (string ⟼ string) with no entries

Then, unload the library.

libraryconfig.unload

Get Information About the Host Process

Use the CLibraryConfiguration object created from calling the clibConfiguration function to get information about the host process. These object properties provide information about the settings and status of the MATLAB interface to a C++ library.

  • InterfaceLibraryPath contains the path to the interface library.

  • Libraries contains the names of libraries used to build the interface.

  • Loaded contains the process status, specified as 1 if the library is loaded and 0 if the library is not loaded.

  • ExecutionMode indicates whether to load the C++ library interface in the same process as MATLAB, specified as inprocess or outofprocess.

  • ProcessName contains the name of the host process. The default name for an out-of-process host is MATLABCLibHost.

  • ProcessID contains the process identifier.

  • OutOfProcessEnvironmentVariables contains one or more system environment variable names and values used by the interface to the C++ library. You can view environment variables in out-of-process mode only.

See Also

Objects

Functions

Topics