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-файлов в том же каталоге, что и сам mex-файл, должен находиться m-файл. В приведённом выше примере это должен быть файл 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.