MATLAB Compiler

C Example

Suppose you have a C function that reads data from a measurement device. In M-code, you want to simulate the device by providing a sine wave output. In production, you want to provide a function that returns the measurement obtained from the device. You have a C function called measure_from_device() that returns a double, which is the current measurement.

collect.m contains the M-code for the simulation of your application:

• function collect
  
  y = zeros(1, 100); %Pre-allocate the matrix 
  for i = 1:100 
     y(i) = collect_one;
  end
  
  function y = collect_one
  
  persistent t;
  if (isempty(t))
     t = 0;
  end
  t = t + 0.05;
  y = sin(t);
  

The next step is to replace the implementation of the collect_one function with a C implementation that provides the correct value from the device each time it is requested. This is accomplished by using the %#external pragma.

The %#external pragma informs the MATLAB Compiler that the implementation version of the function (Mf) will be hand written and will not be generated from the M-code. This pragma affects only the single function in which it appears. Any M-function may contain this pragma (local, global, private, or method). When using this pragma, the Compiler will generate an additional header file called file_external.h or file_external.hpp, where file is the name of the initial M-file containing the %#external pragma. This header file will contain the extern declaration of the function that the user must provide. This function must conform to the same interface as the Compiler-generated code.

The Compiler will still generate a .c or .cpp file from the .m file in question. The Compiler will generate the feval table, which includes the function and all of the required interface functions for the M-function, but the body of M-code from that function will be ignored. It will be replaced by the hand-written code. The Compiler will generate the interface for any functions that contain the %#external pragma into a separate file called file_external.h or file_external.hpp. The Compiler-generated C or C++ file will include this header file to get the declaration of the function being provided.

In this example, place the pragma in the collect_one local function:

• function collect
  
  y = zeros(1, 100); % pre-allocate the matrix 
  for i = 1:100 
     y(i) = collect_one; 
  end
  
  function y = collect_one 
  
  %#external
  persistent t;
  if (isempty(t)) 
     t = 0; 
  end 
  t = t + 0.05; 
  end 
  y = sin(t);
  

When this file is compiled, the Compiler creates the additional header file collect_external.h, which contains the interface between the Compiler-generated code and your code. In this example, it would contain

• extern mxArray * Mcollect_collect_one(int nargout_);
  

We recommend that you include this header file when defining the function. This function could be implemented in this C file, measure.c, using the measure_from_device() function.

• #include "matlab.h"
  #include "collect_external.h"
  #include <math.h>
  
  extern double measure_from_device(void);
  
  mxArray * Mcollect_collect_one(int nargout_);
  { 
     return( mlfScalar( measure_from_device() )); 
  }
  double measure_from_device(void)
  {
     static double t = 0.0;
     t = t + 0.05;
     return sin(t);
  }
  

In general, the Compiler will use the same interface for this function as it would generate. To generate the C code and header file, use

• mcc -mc collect.m
  

By examining the Compiler-generated C code, you should easily be able to determine how to implement this interface. To compile collect.m to a MEX-file, use

• mcc -x collect.m measure.c
  

Interfacing M-Code to C/C++ Code

Using Pragmas