matlab::cpplib::initMATLABLibrary

Initialize a library of MATLAB functions packaged in a deployable archive file

Description

std::unique_ptr<MATLABLibrary> initMATLABLibrary(std::shared_ptr<MATLABApplication> application, const std::u16string & ctfPath)

std::unique_ptr<MATLABLibrary> initMATLABLibrary(std::shared_ptr<MATLABApplication> application, const std::u16string & ctfPath, const std::u16string& session_key = std::u16string())

The initMATLABLibrary function initializes a library of MATLAB® functions packaged in a deployable archive (.ctf file) and returns a unique pointer to that library. It requires a shared pointer to a MATLABApplication instance and a path to the archive file. You can optionally provide a hex encoded 64 byte AES decryption key to decrypt the library at runtime.

The path to the deployable archive is either relative or absolute. If the path is relative, the following paths are prepended in the order specified below until the file is found or all possibilities are exhausted.

  1. The value of the environment variable CPPSHARED_BASE_CTF_PATH if it is defined.

  2. The working folder.

  3. The folder where the executable is located.

  4. On macOS systems the folder three levels above the executable location.

If the library is found it is initialized and a pointer is returned. Otherwise the function throws an exception.

Lifecycle and Instance Management

The initMATLABLibrary function manages library instances differently than the legacy mwArray API based shared library target. In versions using the mwArray API multiple initialization calls for the same component within a single process typically shared a single in process instance of MATLAB Runtime.

When you use the MATLAB Data API (C++11) each call to initMATLABLibrary creates a distinct library instance. This instance is owned by the returned std::unique_ptr<MATLABLibrary> smart pointer which automatically handles the cleanup and termination of the library when the pointer goes out of scope. While this design provides better isolation between components it means the developer must decide where to define the pointer scope to ensure the library remains available for the duration of its intended use. To replicate the legacy behavior of the mwArray API where only one instance exists for a component you should initialize the library once and share the resulting pointer across your application.

Parameters

std::shared_ptr<MATLABApplication> application

Pointer to a MATLABApplication object returned from initMATLABApplication.

const std::u16string & ctfPath

Relative or absolute path to the archive.

const std::u16string& session_key = std::u16string()

AES decryption key, specified as a hex encoded AES key with a 64 byte file size.

For more details, see mcc -k.

Return Value

std::unique_ptr<MATLABLibrary>

Pointer to a MATLABLibrary object that is used to call functions from the library, feval etc.

Exceptions

matlab::cpplib::LibNotFound

No library with the given name is found on the shared library path.

matlab::cpplib::LibInitErr

Library cannot be initialized.

Examples

Initialize MATLABLibrary

std::vector<std::u16string> opts = {u"-nojvm"};
auto matlabPtr = initMATLABApplication(MATLABApplicationMode::IN_PROCESS, opts);
auto libAstro = initMATLABLibrary(matlabPtr, convertUTF8StringToUTF16String("astro.ctf"));

Version History

Introduced in R2018a

See Also

| | | | | | |