共享库函数

MATLAB^® Compiler SDK™ 生成的 C 或 C++共享库至少包含七个函数。有三个生成的函数来管理库的初始化和终止，一个用于打印输出和错误消息，以及两个为库中包含的每个 MATLAB 函数生成的函数。

要生成本节描述的函数，首先将文件夹 matlabroot\extern\examples\compilersdk\c_cpp\triangle 复制到当前工作目录。

按照以下过程创建一个名为 libtriangle 的共享库，其中包含函数 sierpinski.m使用 MATLAB 代码创建 C 共享库，生成 C++ mwArray API 共享库并编译 C++ 应用程序，或者生成 C++ MATLAB Data API 共享库并编译 C++ 应用程序，具体取决于所需的目标应用程序。

应用程序类型

创建共享库后，执行与目标语言相对应的 mbuild 命令。此命令使用您的 C/C++ 编译器编译代码并将驱动程序代码与 MATLAB Compiler SDK 生成的 C/C++ 共享库链接。

对于 C 应用程序，使用 mbuild triangle.c libtriangle.lib。

对于 C++ mwArray API 应用程序，请使用 mbuild triangle_mwarray.cpp libtriangle.lib

对于 C++ MATLAB Data API 应用程序，使用 mbuild triangle_mda.cpp

这些命令创建一个以所选源代码文件命名的主程序，该程序调用 libtriangle 共享库中的函数。该库导出一个函数（包含在 sierpinski.m 中），该函数使用简单的迭代算法来生成称为谢尔宾斯基三角形的分形。主程序可以选择采用单个数字参量来指定用于生成分形的点数。例如，triangle 8000 生成一个包含 8,000 个点的图。

调用共享库的程序的结构

所有调用 MATLAB Compiler SDK 生成的共享库的程序都具有大致相同的结构。

库初始化和终止函数

库初始化和终止函数分别创建和销毁共享库所需的 MATLAB Runtime 实例。在调用共享库中的任何其他函数之前，您必须调用初始化函数，并且在完成对共享库的调用之后，您应该调用终止函数，否则可能会有内存泄漏的风险。

对于使用 mwArray API 的 C 共享库和 C++ 共享库，初始化函数 <library>Initialize[WithHandlers] 有多种形式，终止函数 <library>Terminate 有一种形式。您生成的 C/C++ 共享库的名称用作函数名称的一部分。初始化函数的最简单形式不需要任何参量；很可能，这是您的应用程序将调用的版本。在这个示例中，这种形式的初始化函数被称为 libtriangleInitialize。

bool libtriangleInitialize(void)

此函数使用默认打印和错误处理程序以及编译过程中生成的其他信息创建 MATLAB Runtime 实例。

但是，如果您想要更好地控制如何处理打印输出和错误消息，请调用该函数的第二种形式，它接受两个参量。在这个示例中，这种形式的初始化函数被称为 libtriangleInitializeWithHandlers。

bool libtriangleInitializeWithKey(
    const char* session_key
)

通过调用此函数语法，您可以提供由 MATLAB Runtime 调用的打印和错误处理例程的自己的版本。这些例程都具有相同的签名（有关完整详细信息，请参阅打印和错误处理函数）。通过覆盖默认值，您可以控制输出的显示方式，例如，是否将输出放入日志文件。

如果您已经使用 mcc -k 选项通过 AES 加密密钥编译了 C++ 共享库，则可以使用名为 libtriangleInitializeWithKey 的初始化函数的另一种形式。此语法允许您在 C++ 应用程序中运行时提供解密密钥，而不是使用 MEX 加载程序。

bool libtriangleInitializeWithHandlers(
    mclOutputHandlerFcn error_handler,
    mclOutputHandlerFcn print_handler
)

您还可以使用语法 libtriangleInitializeWithHandlersAndKey 指定错误处理程序、打印处理程序和解密密钥。

在 Microsoft^® Windows 平台上，MATLAB Compiler SDK 生成一个额外的初始化函数：标准 Microsoft DLL 初始化函数 DllMain。

BOOL WINAPI DllMain(HINSTANCE hInstance, DWORD dwReason,  
                    void *pv)

生成的 DllMain 执行一项非常重要的服务；它定位共享库在磁盘上的存储目录。此信息用于查找可部署存档，如果没有该存档，应用程序将无法运行。如果您修改生成的 DllMain（不推荐），请确保保留其这部分功能。

库的终止很简单。

void libtriangleTerminate(void)

在调用 mclTerminateApplication 之前调用此函数（每个库调用一次）。

打印和错误处理函数

默认情况下，MATLAB Compiler SDK 生成的应用程序和共享库将打印输出发送到标准输出，将错误消息发送到标准错误。MATLAB MATLAB Compiler SDK 生成一个默认打印处理程序和一个默认错误处理程序来实现此策略。如果您想改变这种行为，您必须编写自己的错误和打印处理程序并将它们传递给适当的生成的初始化函数。

您可以替换这两个函数中的一个、两个或者都不替换。MATLAB Runtime 通过打印处理程序发送所有常规输出，通过错误处理程序发送所有错误输出。因此，如果您重新定义这两个函数中的任何一个，MATLAB Runtime 将对所有属于其调用该处理程序的类的输出使用该函数的版本。

默认打印处理程序采用以下形式。

static int mclDefaultPrintHandler(const char *s)

实现很简单；它接受一个字符串，将其打印在标准输出上，并返回打印的字符数。如果您覆盖或替换此函数，您的版本还必须采用字符串并返回“已处理”的字符数。当执行的 MATLAB 文件请求打印输出时，MATLAB Runtime 会调用打印处理程序（例如通过 MATLAB 函数 disp。打印处理程序不会以回车符或换行符来终止输出。

默认错误处理程序与打印处理程序具有相同的形式。

static int mclDefaultErrorHandler(const char *s)

但是，打印处理程序的默认实现略有不同。它将输出发送到标准错误输出流，但如果字符串不是以回车符结尾，错误处理程序就会添加一个。如果您用自己的错误处理程序替换默认错误处理程序，则也应该执行此检查，否则 MATLAB 运行时打印的某些错误消息将无法正确格式化。

有关在应用程序中使用自定义打印和错误处理函数的示例，请参阅位于 matlabroot\extern\examples\compilersdk\c_cpp\catcherror 的文件。

extern "C" int myPrintHandler(const char *s); 

从 MATLAB 文件生成的函数

对于 MATLAB Compiler SDK 命令行上指定的每个 MATLAB 文件，产品都会生成两个函数，即 mlx 函数和 mlf 函数。每个生成的函数都执行相同的操作（调用您的 MATLAB 文件函数）。这两个函数有不同的名称并且呈现不同的接口。每个函数的名称均基于 MATLAB 文件中第一个函数的名称（本例中为 sierpinski）；每个函数都以不同的三个字母的前缀开头。

void mlxSierpinski(int nlhs, mxArray *plhs[], int nrhs,
                   mxArray *prhs[])

void mlfSierpinski(int nargout, mxArray** x, mxArray** y,
                   mxArray* iterations, mxArray* draw)

mlfSierpinski(2, &x, &y, iterations, draw);

[a,b,varargout] = myfun(x,y,z,varargin)

void mlfMyfun(int numOfRetVars, mxArray **a, mxArray **b, 
              mxArray **varargout, mxArray *x, mxArray *y,
              mxArray *z, mxArray *varargin)

... 'FOO' : function does not take 0 arguments

  mwArray junk; 
  FOO(junk); 

 FOO((mwArray)NULL);

No input no output:
void foo() 

Only inputs:
void foo(const mwArray& varargin)

Only outputs:
void foo(int nargout, mwArray& varargout)

Most generic form that has both inputs and outputs:
void foo(int nargout, mwArray& varargout, 
                       const mwArray& varargin) 

Most generic form that has outputs and all the inputs
void foo(int nargout, mwArray& varargout, const 
                             mwArray& i1, const 
                             mwArray& i2, const 
                              mwArray& varargin)

Only inputs:
void foo(const mwArray& i1, 
      const mwArray& i2, const mwArray& varargin)

Most generic form that has all the outputs and inputs
void foo(int nargout, mwArray& o1, mwArray& o2, 
                            mwArray& varargout, 
                        const mwArray& varargin)


Only outputs:
void foo(int nargout, mwArray& o1, mwArray& o2, 
                                   mwArray& varargout)

Most generic form that has all the outputs and 
                                      all the inputs
void foo(int nargout, mwArray& o1, mwArray& o2, 

mwArray& varargout, 
         const mwArray& i1, const mwArray& i2, 
                       const mwArray& varargin)

使用共享库时检索 MATLAB Runtime 状态信息

使用共享库时，您可以调用函数从 MATLAB Runtime 状态中检索特定信息。有关详细信息，请参阅设置和检索共享库的 MATLAB Runtime 数据。