Can I make use of OpenMP in my MATLAB MEX-files?

I would like to make use of the OpenMP parallel programming features in my MATLAB MEX-files; is this supported?

Answer 1

[MathWorks Support Team]

MathWorks does not specifically test or support using OpenMP in customer written MATLAB MEX-files. The article below discusses a number of points however which should help you in successfully using OpenMP in MEX-files.

*Compiler Support*

To be able to make use of OpenMP you will first of all need a C/C++ compiler which supports OpenMP.

- On Windows: not all supported MEX compilers support OpenMP. For example Microsoft Windows SDK 7.1 does not, neither do many of the Microsoft Visual C++ Express editions which are supported MEX compilers in older MATLAB versions. Typically the Microsoft Visual C++ Professional Editions do support OpenMP however.

- On Mac: the default MEX Compiler in recent MATLAB for Mac versions is clang as included with Xcode 5.x and 6.x. The clang compilers included in Xcode 5 and 6 do not support OpenMP. MathWorks does not offer support whatsoever on trying to use other than the officially supported MEX compilers; in theory it should be possible however to for example use gcc/g++ (compiled by yourself or obtained elsewhere) on Mac to create MATLAB MEX-files.

- On Linux: the supported MEX compilers gcc/g++ typically support OpenMP without problems.

*Incompatibilities between OpenMP implementations*

Microsoft Visual C++ will by default link your objects to Microsoft's OpenMP implementation, gcc/g++ will typically link against libgomp (GNU OpenMP). MATLAB itself makes use of Intel's OpenMP implementation however, this can lead to incompatibilities when executing your MEX-file linked against Microsoft OpenMP or GOMP, in MATLAB. To prevent running into these incompatibilities we recommend you also use Intel's OpenMP implementation in your MEX-files. The following page on the Intel website explains how various non-Intel compilers and linkers (like gcc/g++ and Microsoft Visual C++) can be used to compile code for- and link against Intel's OpenMP:

https://software.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/optimization-and-programming-guide/openmp-support/openmp-library-support/using-the-openmp-libraries.html

See the documentation page for "mex" to learn more about how to override the compiler and linker flags when calling "mex" such that you can apply the correct flags. To open this page type "doc mex" in your MATLAB Command Window, or consult the online documentation (note the following link is specific for MATLAB release R2020a):

https://www.mathworks.com/help/releases/R2020a/matlab/ref/mex.html#btw193g-1

Further, the Intel OpenMP import libraries (libiomp5.lib/so/dylib) can be found in your bin\win32 or bin\win64 directories for 32- and 64-bit MATLAB on Windows respectively and in the sys/os/glnxa64 directory of your MATLAB installation on Linux and sys/os/maci64 on Mac.

*Version Compatibility*

The MATLAB documentation states that "for best results, your version of MATLAB must be the same version that was used to create the MEX-file" but also that "MEX-files are usually backward compatible." For MEX-files which make use of OpenMP and which were linked according to the instructions above, the former holds true but the latter does not. You should rebuild and relink your OpenMP MEX-files for each MATLAB release which you are working with.

 

Answer 2

[James Tursa]

You left out one extremely important detail. The API functions that use the MATLAB Memory Manager are not thread-safe! That is, you should never use any API functions that allocate memory inside of a parallel thread ... doing so will typically crash MATLAB.

Examples of API function that do not allocate memory (and hence are thread-safe):
mxGetPr
mxGetPi
mxGetIr
mxGetJc
mxGetNumberOfDimensions
etc.

Examples of API functions that do allocate memory (and hence are not thread-safe):
mxArrayToString
mxCreateDoubleMatrix
mxCreateNumericArray
etc.

Questionable:
mxGetDimensions if mwSize does not match size_t

For the last one, if mwSize matches size_t (i.e., both 32-bit or both 64-bit), then the mxGetDimensions call returns a pointer to the actual dimensions array that is part of the mxArray. In that case the call is probably thread-safe. But if they don't match, then the mxGetDimensions call will return a pointer to a copy of the dimensions array. This is not discussed in the documentation, so it is unclear to me if this copy was already pre-allocated at the time of the mxArray creation (in which case the call would be thread-safe) or if the mxGetDimensions call itself does an allocation (in which case the call would not be thread-safe). I haven't tried tests cases to try and determine this, so caveat emptor.

BOTTOM LINE: If you need to use API functions that allocate memory, do it outside of your parallel threads!

[Jim Hokanson]

Relevant link:

https://www.mathworks.com/matlabcentral/answers/418782-thread-safety-of-mx-mex-functions?s_tid=mlc_ans_email_view#comment_610154

[Peter Cook]

@Tim Davis,

One technique I use to circumvent mxMalloc/mxCalloc is to put my heavy lifter functions in a header file (separate from wherever mexFunction sits) and send pointers to MATLAB input data sources (via mxGetData) to these functions, I can then dynamically manage memory normally with malloc/calloc/realloc/free over there. Basically anything I write in pure C/C++ without mex.h header functions live there.

As for output data, I haven't run into trouble (yet?) with OpenMP by using plhs[k] = mxCreateNumericArray(...) in mexFunction and shipping a pointer to that array over to get filled in (except when trying to use strided/pitched/aligned pointers).

Also, in general when working with OpenMP (which, disclaimer, I have not been doing that long, likely much less time than you) I try to preallocate whatever is coming out of the parallel loop and just shift pointers around via omp_get_thread_num(). I peeked at SuiteSparse on GitHub and couldn't really assess if this was an option in your application.

[James Tursa]

Can you create a minimum working example that crashes and post it?

[Bruno Luong]

I have written Mex with omp_set_num_threads to a number and pragma omp parallel for and it works just fine.