A.2.1 Начало работы с Mex-файлами

Основная команда для создания mex-файла — либо mkoctfile --mex или mex. Первую команду можно использовать как изнутри Octave, так и из командной строки. Чтобы избежать проблем с собственным mex команд MATLAB, использование команды mex ограничено использованием в Octave. Скомпилированные mex-файлы имеют расширение .mex.

: mex [-options] file … ¶

: status = mex (…) ¶

Компилирует исходный код на C, C++ или Fortran в MEX-файл.

status — это возвращаемый код функции mkoctfile.

Если компиляция завершится ошибкой, а возвращаемое значение не запрашивается, возникает ошибка. Однако, если программист запросит status, Octave просто выдаст предупреждение, и программисту необходимо самостоятельно проверить, была ли команда выполнена успешно.

Это эквивалентно mkoctfile --mex [-options] file.

См. также: mkoctfile, mexext.

: ext = mexext () ¶

Возвращает расширение файла MEX.

Примечание для программистов: Octave использует расширение mex для всех MEX-файлов независимо от операционной системы (Linux, Windows, Apple) или разрядности оборудования (32-битное или 64-битное).

См. также: mex.

Рассмотрим следующий короткий пример:

#include "mex.h"

void
mexFunction (int nlhs, mxArray *plhs[],
             int nrhs, const mxArray *prhs[])
{
  mexPrintf ("Hello, World!\n");

  mexPrintf ("I have %d inputs and %d outputs\n", nrhs, nlhs);

  /* Return empty matrices for any outputs */
  int i;
  for (i = 0; i < nlhs; i++)
    plhs[i] = mxCreateDoubleMatrix (0, 0, mxREAL);
}

Первая строка #include "mex.h" делает доступными все определения, необходимые для mex-файла. Важное отличие между Octave и MATLAB заключается в том, что заголовочный файл "matrix.h" подключается неявно через подключение "mex.h". Это необходимо для предотвращения конфликта с файлом Octave "Matrix.h" для операционных систем и компиляторов, которые не различают имена файлов в верхнем и нижнем регистре.

Точка входа в mex-файл определяется mexFunction. Функция принимает четыре аргумента:

1. Количество возвращаемых аргументов (# аргументов слева).
2. Массив указателей на возвращаемые аргументы.
3. Количество входных аргументов (# аргументов справа).
4. Массив указателей на входные аргументы.

Обратите внимание, что определение имени функции не включено явно в mexFunction, и поэтому может быть только один mexFunction точка входа на файл. Вместо этого имя функции, видимое в Octave, определяется именем самого mex-файла без расширения. Если вышеупомянутая функция находится в файле myhello.c, она может быть скомпилирована с

mkoctfile --mex myhello.c

что создает файл myhello.mex. Функцию затем можно запустить из Octave как

myhello (1,2,3)
⇒ Hello, World!
⇒ I have 3 inputs and 0 outputs

Следует отметить, что mex-файл не содержит строки справки. Для документирования mex-файлов должен существовать файл m в той же директории, что и сам mex-файл. Принимая вышеприведенный пример, должен быть файл myhello.m, который может содержать текст

%MYHELLO Simple test of the functionality of a mex-file.

В этом случае функция, которая будет выполняться в Octave, будет определяться mex-файлом, а строка справки — файлом m. Это также может быть полезно для предоставления примерного имплементирования mex-файла в самом языке Octave для целей тестирования.

Хотя в одном mex-файле не может быть нескольких точек входа, можно использовать функцию mexFunctionName для определения того, с каким именем был вызван mex-файл. Это можно использовать для изменения поведения mex-файла в зависимости от имени функции. Например, если

#include "mex.h"

void
mexFunction (int nlhs, mxArray *plhs[],
             int nrhs, const mxArray *prhs[])
{
  const char *nm;

  nm = mexFunctionName ();
  mexPrintf ("You called function: %s\n", nm);
  if (strcmp (nm, "myfunc") == 0)
    mexPrintf ("This is the principal function\n", nm);

  return;
}

находится в файле myfunc.c и компилируется с

mkoctfile --mex myfunc.c
ln -s myfunc.mex myfunc2.mex

то, как видно из

myfunc ()
⇒ You called function: myfunc
    This is the principal function
myfunc2 ()
⇒ You called function: myfunc2

поведение mex-файла может быть изменено в зависимости от имени функции.

Хотя пользователь должен включать только mex.h в свой код, Octave объявляет дополнительные функции, определения типов и т. д., доступные пользователю для написания mex-файлов в заголовочных файлах mexproto.h и mxarray.h.