It is not a secret that MATLAB has many undocumented (or deliberately hidden) features and commands. There are even excellent website & book devoted specifically to this topic: Undocumented Matlab
However most of the findings are related to MATLAB language itself and investigations on undocumented MEX API seems to be missing (or scarce at least).
During development of our toolbox we have found lots of hidden functions which can be helpful for creating speed-efficient extensions for MATLAB using native languages.
Here we want to explain some of them in details and provide complete list of undocumented MEX API functions.
Please note that there is a risk in using the functions – MathWorks can change / remove some of them in next versions. It is additional burden for developer to stay tuned and update their toolboxes on time.
Reduced OOP capabilities of MATLAB
Starting from version 2008b MATLAB allows user to introduce custom-type classes by
classdef keyword. MATLAB was late on adding object oriented features – I can only image how hard it was for developers at MathWorks to add OOP constructs to purely procedural language which follows entirely different philosophy. (Yes, objects could be created using structs and special folder structure in earlier version of MATLAB – but that was just ugly design, MathWorks will not support it in future).
They still don’t have full support for OOP features though. The most important missing features are:
- It is prohibited to have destructor for custom non-handle classes.
- It is not possible to overload assignment-without-subscripts operator (e.g. A = B).
I don’t know the reasons why these fundamental OOP paradigms are not implemented in MATLAB – but this disables creating powerful virtual machine-type of toolboxes.
In that case MATLAB objects would have only one property field – ‘id’, identifier of variable stored in MEX module – virtual machine (e.g. pointer to C++/C object). MEX module would only need to know ‘id’ of objects and what operation to conduct with them (+, -, *, etc.) – all processing would be done in MEX. Heavy data exchange between MATLAB and MEX libraries would be completely unnecessary. MATLAB would act as just an interpreter in such scenario. Moreover MEX API could be simplified to several functions only.
Deep-Copy access to object properties from MEX library (Official)
Unfortunately we are restricted to current architecture – where all the data are allocated / stored on MATLAB side and we have to transfer it from MATLAB to MEX library in order to work with it.
Official MEX API provides two functions to access object properties from within MEX library:
Both functions share the same major problem – they create deep copy of the data!
Imagine the situation when your object is a huge matrix with high-precision elements and it occupies
800MB of RAM. If we want to access it in MEX library (e.g. transpose) we would call
mxGetProperty which will do ENTIRE COPY of your object’s property – wasting another
Obviously this cannot be accepted, not speaking of totally reduced performance (copying could take a while for such amount too).
Copy-Free access to object properties from MEX library (Undocumented)
In search for remedy we found similar (but) undocumented functions we can use to get shared access to objects properties (32-bit):
extern mxArray* mxGetPropertyShared(const mxArray* pa, unsigned int index, const char * propname); extern void mxSetPropertyShared(mxArray* pa, unsigned int index, const char * propname, const mxArray* value);
Functions can be used as one-to-one replacement for official functions.
mxGetPropertyShared just returns pointer to existing property without any copying.
mxDestroyArray can still be called on returned pointer (Thanks to James Tursa for correction).
Full list of MEX API functions
We have extracted full list of usable MEX functions from
libmex.dll (MATLAB 2012b 32-bit) – two main MEX API dynamic libraries. It includes functions from official API as well as undocumented ones:
The distinctive feature of the list – it provides de-mangled C++ names of functions, with type of arguments and return value (not published before to the knowledge of author). This makes usage of undocumented functions much easier.
Take a look on function list – there are a lot of interesting ones, like
mxGetReferenceCount and many others.
Moreover it is possible to see high level C++ classes MathWorks developers use for work. For example, now it is clear that fundamental type
mxArray_tag – is not a plain-old-struct anymore, it has member-functions and behaves more like a class. It even has custom
delete heap management functions and overloaded assignment
operator=. Reverse-engineering of these functions might reveal the exact & complete data structure of
Actually with some effort internal
mxArray_tag class from MathWorks might be used in third-party MEX files now. How much more easier this would be instead of clumsy
Please feel free to leave your requests or comments below.