MATLAB Compiler

Calling a Shared Library

At run-time, there is an MCR instance associated with each individual shared library. Consequently, if an application links against two MATLAB Compiler-generated shared libraries, there will be two MCR instances created at run-time.

You can control the behavior of each MCR instance by using MCR options. The two classes of MCR options are global and local. Global MCR options are identical for each MCR instance in an application. Local MCR options may differ for MCR instances.

To use a shared library, you must use these functions:

• mclInitializeApplication
• mclTerminateApplication

mclInitializeApplication allows you to set the global MCR options. They apply equally to all MCR instances. You must set these options before creating your first MCR instance.

These functions are necessary because some MCR options such as whether or not to start Java, the location of the MCR itself, whether or not to use the MATLAB JIT feature, and so on, are set when the first MCR instance starts and cannot be changed by subsequent instances of the MCR.

Note    You must call mclInitializeApplication once at the beginning of your driver application. You must make this call before calling any other MathWorks functions.

Function Signatures

The function signatures are

• bool mclInitializeApplication(const char **options, int count);
  bool mclTerminateApplication(void); 
  

mclInitializeApplication.   Takes an array of strings of user-settable options (these are the very same options that can be provided to mcc via the -R option) and a count of the number of options (the length of the option array). Returns true for success and false for failure.

mclTerminateApplication.   Takes no arguments and can only be called after all MCR instances have been destroyed. Returns true for success and false for failure.

Note    After you call mclTerminateApplication, you may not call mclInitializeApplication again. No MathWorks functions may be called after mclTerminateApplication.

This C example shows typical usage of the functions.

• int main(){
      
      mxArray *in1, *in2; /* Define input parameters */
      mxArray *out = NULL;/* and output parameters to be passed to 
                             the library functions */
      
      double data[] = {1,2,3,4,5,6,7,8,9};
      
      /* Call the library intialization routine and make sure that 
         the library was initialized properly */
      mclInitializeApplication(NULL,0);
      if (!libmatrixInitialize()){
          fprintf(stderr,"could not initialize the library 
                          properly\n");
          return -1;
      }
  
      /* Create the input data */
      in1 = mxCreateDoubleMatrix(3,3,mxREAL);
      in2 = mxCreateDoubleMatrix(3,3,mxREAL);
      memcpy(mxGetPr(in1), data, 9*sizeof(double));
      memcpy(mxGetPr(in2), data, 9*sizeof(double));
      
      /* Call the library function */
      mlfAddmatrix(1, &out, in1, in2);
      /* Display the return value of the library function */
      printf("The value of added matrix is:\n");
      display(out);
      /* Destroy the return value since this variable will be reused 
         in the next function call. Since we are going to reuse the 
         variable, we have to set it to NULL. Refer to MATLAB 
         Compiler documentation for more information on this. */
      mxDestroyArray(out); out=0;
      mlfMultiplymatrix(1, &out, in1, in2);
      printf("The value of the multiplied matrix is:\n");
      display(out);
      mxDestroyArray(out); out=0;
      mlfEigmatrix(1, &out, in1);
      printf("The Eigen value of the first matrix is:\n");
      display(out);
      mxDestroyArray(out); out=0;
      
      /* Call the library termination routine */
      libmatrixTerminate();
      
      /* Free the memory created */
      mxDestroyArray(in1); in1=0;
      mxDestroyArray(in2); in2 = 0;
      mclTerminateApplication();
      return 0;
  }
  

Note    mclInitializeApplication can only be called once per application. Calling it a second time is an error, and will cause the function to return false. This function must be called before calling any C MX-function or MAT-file API function.

Steps to Use a Shared Library

To use a MATLAB Compiler-generated shared library in your application, you must perform the following steps:

1. Include the generated header file for each library in your application. Each MATLAB Compiler-generated shared library has an associated header file named <libname>.h, where <libname> is the library's name that was passed in on the command line when the library was compiled.
2. Initialize the MATLAB libraries by calling the mclInitializeApplication API function. You must call this function once per application, and it must be called before calling any other MATLAB API functions, such as C MX-functions or C MAT-file functions. mclInitializeApplication must be called before calling any functions in a MATLAB Compiler-generated shared library. You may optionally pass in application-level options to this function. mclInitializeApplication returns a Boolean status code. A return value of true indicates successful initialization, and false indicates failure.
3. For each MATLAB Compiler-generated shared library that you include in your application, call the library's initialization function. This function performs several library-local initializations, such as unpacking the CTF archive, and starting an MCR instance with the necessary information to execute the code in that archive. The library initialization function will be named <libname>Initialize(), where <libname> is the library's name that was passed in on the command line when the library was compiled. This function returns a Boolean status code. A return value of true indicates successful initialization, and false indicates failure.

Note    On Windows, if you want to have your shared library call a MATLAB shared library (as generated by the MATLAB Compiler), the MATLAB library initialization function (e.g., <libname>Initialize) cannot be called from your shared library during the DllMain(DLL_ATTACH_PROCESS) call. This applies whether the intermediate shared library is implicitly or explicitly loaded. You must place the call somewhere after DllMain().

4. Call the exported functions of each library as needed. Use the C MX API to process input and output arguments for these functions.
5. When your application no longer needs a given library, call the library's termination function. This function frees the resources associated with its MCR instance. The library termination function will be named <libname>Terminate(), where <libname> is the library's name that was passed in on the command line when the library was compiled. Once a library has been terminated, that library's exported functions should not be called again in the application.
6. When your application no longer needs to call any MATLAB Compiler-generated libraries, call the mclTerminateApplication API function. This function frees application-level resources used by the MCR. Once you call this function, no further calls can be made to MATLAB Compiler-generated libraries in the application.

C Shared Library Example

C++ Shared Library Target

© 1994-2005 The MathWorks, Inc.