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 several points that should help you in successfully using OpenMP in MEX-files.

*Compiler Support*

To utilize OpenMP, you will first need a C/C++ compiler that supports OpenMP.

- On Windows: not all supported MEX compilers support OpenMP. For example, Microsoft Windows SDK 7.1 does not, nor 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.

- 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 for using compilers other than the officially supported MEX compilers; however, it should theoretically be possible to 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, while gcc/g++ will typically link against libgomp (GNU OpenMP). MATLAB itself uses Intel's OpenMP implementation, which can lead to incompatibilities when executing your MEX-file linked against Microsoft OpenMP or GOMP in MATLAB. To avoid these incompatibilities, we recommend using 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

To learn more about how to override the compiler and linker flags when calling "mex" so that you can apply the correct flags, refer to the documentation page for "mex". You can open this page by typing "doc mex" in your MATLAB Command Window.

For release-specific documentation, please run the following command in the MATLAB R2020b command window:

>> web(fullfile(docroot, 'matlab/ref/mex.html'))

Furthermore, 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 that use OpenMP and are 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 you are working with.

Please use the below link to search for the required information in the current release: 

https://www.mathworks.com/help/ 

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.