C++ Mex function being passed a MATLAB class object

In my application, I want to have a mex function that accepts an argument that is a custom (but simple) class object with class properties.

The mex function should also return a congruent class object, but having different values (properties). Something like:

myObjectCopy = mxDuplicateArray( prhs[0] ); // Has a .data property
mxSetProperty(myObjectCopy, 0, "data", mxCreateDoubleScalar(4.9) );
plhs[0] = myObjectCopy;

I'm having some access violation issues during successive calls, and I suspect that mxDuplicateArray() may not be creating a deep copy for class objects.

I'd appreciate any definitive advice.

Answer 1

[James Tursa]

mxDuplicateArray( ) does indeed create deep copies ... or at least it used to. Not sure why that would have changed. There might be issues with resources in some classdef objects, but for simple classdef objects like you describe above there should be no problem with access violations or seg faults. E.g., take this code:

% myObject.m
classdef myObject
    properties
        data;
    end
end

and

// objectdata.cpp
#include "mex.h"
void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
{
    mxArray *myObjectCopy;
    myObjectCopy = mxDuplicateArray( prhs[0] ); // Has a .data property
    mxSetProperty(myObjectCopy, 0, "data", mxCreateDoubleScalar(4.9) );
    plhs[0] = myObjectCopy;
    }

Compile the mex routine:

>> mex objectdata.cpp
Building with 'MinGW64 Compiler (C++)'.
MEX completed successfully.

Run it:

>> mo = myObject
mo = 
myObject with properties:

data: []
>> mo.data = 3.4
mo = 
myObject with properties:

data: 3.4000
>> mr = objectdata(mo)
mr = 
myObject with properties:

data: 4.9000
>> mr = objectdata(mo)
mr = 
myObject with properties:

data: 4.9000
>> mr = objectdata(mo)
mr = 
myObject with properties:

data: 4.9000
>> mr = objectdata(mo)
mr = 
myObject with properties:

data: 4.9000
>> mr = objectdata(mo)
mr = 
myObject with properties:

data: 4.9000
>> for k=1:100000; mr = objectdata(mo);end
>>

I don't have any issues with calling this mex routine repeatedly. Can you provide us with more complete code and details of your class?

I believe mxSetProperty( ) takes care of destroying the current data property in the background so that you don't have a memory leak, although this is not documented. E.g., as evidence, this doesn't run out of memory:

>> mo.data = rand(1,100000000);
>> for k=1:10000000; mr = objectdata(mo);end
>> 

Note that this is different behavior from mxSetCell( ) for cell arrays and mxSetField( ) for struct arrays, where you would get a memory leak if you did not manually properly destroy the existing cell or field element first.

*** EDIT #1 ***

So, I put in some memory prints surrounding the mxDuplicateArray( ) calls and got something unexpected, at least to me:

// objectdata2.cpp
#include "mex.h"
void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
{
    mxArray *myObjectCopy;
    mexPrintf("\n\nBefore mxDuplicateArray call ...\n\n");
    mexCallMATLAB(0,NULL,0,NULL,"memory");
    myObjectCopy = mxDuplicateArray( prhs[0] ); // Has a .data property
    mexPrintf("\n\nAfter mxDuplicateArray call ...\n\n");
    mexCallMATLAB(0,NULL,0,NULL,"memory");
    mxSetProperty(myObjectCopy, 0, "data", mxCreateDoubleScalar(4.9) );
    plhs[0] = myObjectCopy;
    }

Running:

>> mo = myObject
mo = 
myObject with properties:

data: []
>> mo.data = rand(1,100000000);
>> mr = objectdata2(mo)


Before mxDuplicateArray call ...
    
Maximum possible array:        3338 MB (3.500e+09 bytes) *
Memory available for all arrays:        3338 MB (3.500e+09 bytes) *
Memory used by MATLAB:        3160 MB (3.313e+09 bytes)
Physical Memory (RAM):       16073 MB (1.685e+10 bytes)

*  Limited by System Memory (physical + swap file) available.


After mxDuplicateArray call ...
    
Maximum possible array:        3339 MB (3.501e+09 bytes) *
Memory available for all arrays:        3339 MB (3.501e+09 bytes) *
Memory used by MATLAB:        3160 MB (3.313e+09 bytes)
Physical Memory (RAM):       16073 MB (1.685e+10 bytes)

*  Limited by System Memory (physical + swap file) available.
mr = 
myObject with properties:

data: 4.9000

The memory footprint did not go up when mxDuplicateArray( ) was called, even though the data property is 763MB and should be easy to see. I may have to retract what I said about mxDuplicateArray( ) when dealing with classdef objects. These don't look like deep copies to me now. Because you don't have direct access to the properties, maybe MATLAB is in fact doing shared data copies behind the scenes.

That being said, I still don't know why you would be getting seg faults. It would help if you posted a small complete example that demonstrates the problem.

*** EDIT #2 ***

To confirm this:

// mxDuplicateArray.c
#include "mex.h"
void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
{
    plhs[0] = mxDuplicateArray( prhs[0] ); // Has a .data property
    }

and

// datapointers.c
#include "mex.h"
void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
{
    mexPrintf("pr = %p\n",mxGetData(prhs[0]));
    }

gives this:

>> mo = myObject
mo = 
myObject with properties:

data: []
>> mo.data = rand(1,100000000);
>> mr = mxDuplicateArray(mo)
mr = 
myObject with properties:

data: [1×100000000 double]
>> datapointers(mo.data)
pr = 000002E1FF6DF060
>> datapointers(mr.data)
pr = 000002E1FF6DF060

So, yes, it is confirmed that mxDuplicateArray( ) does a shared data copy in the background when working with classdef objects (same data pointer). Surprising to me, but there it is.

[AJ]

Thanks for the comprehensive look. Per your suggestion, I created a failing set of code.

The MATLAB class:

% myObject.m
classdef myObject
    properties
        data(1,4) double % Fixed length for testing convenience
    end % properties
    methods
        function obj = myObject(myData)
            if nargin >= 1
                obj.data = myData;
            end
        end % function myObject (constructor)
    end % methods
end % classdef

The C mex code:

// objectdata.cpp
#include "mex.h"

// A static/global
mxArray *myObjectTemplate = NULL;

#define MEXASSERT(test,errString) if (!(test)) mexErrMsgTxt(errString)
void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
{
    double *pDataIn;
    double *pDataOut;
    mxArray *pMxDataPropertyIn;
    mxArray *pMxDataPropertyOut;
    size_t numberOfElements;

    // Stash a copy of the class object away for later duplication (first call, only)
    if (myObjectTemplate == NULL)
        myObjectTemplate = mxDuplicateArray( prhs[0] ); // Has a .data property

    pMxDataPropertyIn = mxGetProperty(prhs[0],0,"data");
    MEXASSERT(pMxDataPropertyIn != NULL,"mxGetProperty(prhs[0]) failed");

    pDataIn = mxGetDoubles(pMxDataPropertyIn);
    MEXASSERT(pMxDataPropertyIn != NULL,"mxGetDoubles(pMxDataPropertyIn) failed");
    numberOfElements = mxGetNumberOfElements(pMxDataPropertyIn);

    plhs[0] = mxDuplicateArray(myObjectTemplate);
    /* This causes access violation on the second call:
    // ==== START TRIAL 1 - Overlay existing data within .data proiperty
    pMxDataPropertyOut = mxGetProperty(plhs[0],0,"data");
    MEXASSERT(pMxDataPropertyOut != NULL,"mxGetProperty(plhs[0]) failed");

    // ==== END TRIAL 1
    */

    // ==== START TRIAL 2 - Create a new data array and pop it in the class object. Memory leak?
    pMxDataPropertyOut = mxCreateDoubleMatrix(1, numberOfElements, mxREAL);
    MEXASSERT(pMxDataPropertyOut != NULL,"mxCreateDoubleMatrix() failed");
    mxSetProperty(plhs[0],0,"data",pMxDataPropertyOut); // Why no return code for this function???
    // ==== END TRIAL 2

    pDataOut = mxGetDoubles(pMxDataPropertyOut);
    MEXASSERT(pDataOut != NULL,"mxGetDoubles(pMxDataPropertyOut) failed");
    
    for (size_t i = 0; i < numberOfElements; i++)
        pDataOut[i] = pDataIn[i] * 2.0;
} // mexFunction()

Compile:

mex -R2018a objectData.cpp

Run:

>> mo = myObject(1:4);
>> mr = objectdata(mo) % First call
mr = 
  myObject with properties:

    data: [0 0 0 0]
>> mr = objectdata(mo) % Second call
Unexpected Standard exception from MEX file.
What() is:bad allocation
.. 

So, no joy. I've combed through the code, but I can't find any flaws expect, perhaps, my expectations of how classes are handled in mex function.

[James Tursa]

I haven't looked at all of this code thoroughly, but the first obvious thing you need to fix that is likely causing the seg faults is the way you store your template. The mxArray pointer itself is a top level variable so it retains its value inbetween mex routine calls.

// A static/global
mxArray *myObjectTemplate = NULL;

And you set it this way:

if (myObjectTemplate == NULL)
    myObjectTemplate = mxDuplicateArray( prhs[0] ); // Has a .data property

That, in and of itself, is fine as far as it goes. However, myObjectTemplate is currently a temporary mxArray as far as the mex routine is concerned. It is on the garbage collection list. As soon as the mex routine returns to the caller, this mxArray (and everything else on the garbage collection list) will be automatically destroyed. Everything that you allocate via mxCreateEtc( ), or mxMalloc( ) and friends, has temporary status inside the mex routine and is on the garbage collection list and will be automatically destroyed (free'd) when the mex routine returns control to the caller. The only exceptions to this are mxArrays that are in the plhs[ ] array, mxArrays that you set into cell or struct arrays, raw memory that you set as data pointers in mxArrays, and mxArrays and memory that you specifically tell MATLAB to remove from the garbage collection list via a mexMakeArrayPersistent( ) (for mxArrays) or mexMakeMemoryPersistent( ) (for raw memory) calls. If you don't do that, then the pointer you stored in myObjectTemplate becomes garbage as soon as the mex routine exits. Any use of this pointer in a subsequent mex routine call will be using garbage, as this does:

    plhs[0] = mxDuplicateArray(myObjectTemplate);

How to fix this? You need to make this mxArray persistent when you store the pointer. And, to avoid a memory leak, you need to add a mexAtExit function to destroy it when the mex routine is cleared from memory. So your code should look something like this:

if (myObjectTemplate == NULL) {
    myObjectTemplate = mxDuplicateArray( prhs[0] ); // Has a .data property
    mexMakeArrayPersistent(myObjectTemplate); // remove from garbage collection list
    mexAtExit(ClearMyObjectTemplate); // function to destroy myObjectTemplate when mex routine is cleared
}

Then the top of your code should look like this:

/ A static/global
mxArray *myObjectTemplate = NULL;

void ClearMyObjectTemplate( )
{
    if( myObjectTemplate ) {
        mxDestroyArray(myObjectTemplate);
        myObjectTemplate = NULL;
    }
}

You need to fix this first and see how your code behaves before we start looking at the rest of your code.

I would also point out that you should add some argument checking in your code to make it robust and production quality. The way it is now, simply typing objectdata at the MATLAB command line without any arguments will crash MATLAB because prhs[0] is not defined but you use it in your code. So always check input arguments for existence, type, complexity, sparsity, etc. before you use them in a mex routine. E.g.,

if (myObjectTemplate == NULL) {
    if( nrhs != 1 || !mxIsClass(prhs[0],"myObject") ) {
        mexErrMsgTxt("Need one myObject input");
    }
    myObjectTemplate = mxDuplicateArray( prhs[0] ); // Has a .data property
    mexMakeArrayPersistent(myObjectTemplate); // remove from garbage collection list
    mexAtExit(ClearMyObjectTemplate); // function to destroy myObjectTemplate when mex routine is cleared
}

And check for the data property being the right class, type, complexity, sparsity, and size before using it, etc. Otherwise dereferencing the data pointer might also crash MATLAB, or worse give you invalid results without crashing.

[AJ]

1. mexMakeArrayPersistent() did solve the access violation problem.
2. The output data is not being assigned to the object property.

I made you suggested updated:

// objectdata.cpp
#include "mex.h"

// A static/global
mxArray *myObjectTemplate = NULL;

void ClearMyObjectTemplate( )
{
    if( myObjectTemplate ) {
        mxDestroyArray(myObjectTemplate);
        myObjectTemplate = NULL;
    }
}

#define MEXASSERT(test,errString) if (!(test)) mexErrMsgTxt(errString)
void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
{
    double *pDataIn;
    double *pDataOut;
    mxArray *pMxDataPropertyIn;
    mxArray *pMxDataPropertyOut;
    size_t numberOfElements;

    // Validation of prhs[] intentionally omitted

    // Stash a copy of the class object away for later duplication (first call, only)
    if (myObjectTemplate == NULL)
    {
        myObjectTemplate = mxDuplicateArray( prhs[0] ); // Has a .data property
        mexMakeArrayPersistent(myObjectTemplate); // remove from garbage collection list
        mexAtExit(ClearMyObjectTemplate); // function to destroy myObjectTemplate when mex routine is cleared
    }

    pMxDataPropertyIn = mxGetProperty(prhs[0],0,"data");
    MEXASSERT(pMxDataPropertyIn != NULL,"mxGetProperty(prhs[0]) failed");

    pDataIn = mxGetDoubles(pMxDataPropertyIn);
    MEXASSERT(pDataIn != NULL,"mxGetDoubles(pMxDataPropertyIn) failed");
    numberOfElements = mxGetNumberOfElements(pMxDataPropertyIn);

    plhs[0] = mxDuplicateArray(myObjectTemplate);
    /* This causes access violation on the second call:
    // ==== START TRIAL 1 - Overlay existing data within .data proiperty
    pMxDataPropertyOut = mxGetProperty(plhs[0],0,"data");
    MEXASSERT(pMxDataPropertyOut != NULL,"mxGetProperty(plhs[0]) failed");

    // ==== END TRIAL 1
    */

    // ==== START TRIAL 2 - Create a new data array and pop it in the class object. Memory leak?
    pMxDataPropertyOut = mxCreateDoubleMatrix(1, numberOfElements, mxREAL);
    MEXASSERT(pMxDataPropertyOut != NULL,"mxCreateDoubleMatrix() failed");
    mxSetProperty(plhs[0],0,"data",pMxDataPropertyOut); // Why no return code for this function???
    // ==== END TRIAL 2

    pDataOut = mxGetDoubles(pMxDataPropertyOut);
    MEXASSERT(pDataOut != NULL,"mxGetDoubles(pMxDataPropertyOut) failed");
    
    for (size_t i = 0; i < numberOfElements; i++)
        pDataOut[i] = pDataIn[i] * 2.0;

    if (nlhs >= 2)
        plhs[1] = pMxDataPropertyOut;
} // mexFunction()

Here are the results:

>> [mr,justData] = objectdata(mo)
mr = 
  myObject with properties:

    data: [0 0 0 0]
justData =
     2     4     6     8

I seem to be at an impasse.

[James Tursa]

You have a misunderstanding of how classdef objects work in a mex routine. I will contrast that behavior with cell and struct arrays.

void mxSetCell(mxArray *pm, mwIndex index, mxArray *value);
void mxSetField(mxArray *pm, mwIndex index, const char *fieldname, mxArray *pvalue);
void mxSetFieldByNumber(mxArray *pm, mwIndex index, int fieldnumber, mxArray *pvalue);

In all three of the above cases, the pointer value itself (not a copy of the mxArray) is actually attached to the cell or struct array. Then value is removed from the garbage collection list (its disposition now being fully determined by whatever happens to its parent). The key point is that a deep copy is NOT made. This is a very shallow copy. Similarly take these API functions:

mxArray *mxGetCell(const mxArray *pm, mwIndex index);
mxArray *mxGetField(const mxArray *pm, mwIndex index, const char *fieldname);
mxArray *mxGetFieldByNumber(const mxArray *pm, mwIndex index, int fieldnumber);

The returned mxArray pointer is the actual pointer from the cell or struct array. It is not any kind of mxArray copy whatsoever. You are pointing into the cell or struct array elements themselves. Whatever you do to the data inside the returned mxArray will be done to the original cell or struct array pm.

Cell and struct arrays are very efficient in mex routines because only shallow copies are involved, not deep copies. The downside is when you want to use the same mxArray repeatedly. There should be an official way to do this in a mex routine but unfortunately there isn't ... you have to resort to hacks (an issue that is beyond the scope of this post).

Now consider the classdef object API functions:

mxArray *mxGetProperty(const mxArray *pa, mwIndex index, const char *propname);

The returned mxArray pointer points to a DEEP copy of the pa object property. I presume, based on the earlier testing above, that if this property itself is a classdef object it will be a shared data copy? Don't know for sure about that and can probably test to determine this, but that is a side point for the present discussion. The main point is that the returned mxArray pointer points to a newly created mxArray, not the original property in pa.

void mxSetProperty(mxArray *pa, mwIndex index, const char *propname, const mxArray *value);

For this case, a DEEP copy is made of value and that is what is attached to pa as the new property (with noted caveat). Any subsequent changes you make to value have no effect on the property in pa because they are not the same mxArray.

Now look at your code:

mxSetProperty(plhs[0],0,"data",pMxDataPropertyOut); // Why no return code for this function???
// ==== END TRIAL 2
pDataOut = mxGetDoubles(pMxDataPropertyOut);
MEXASSERT(pDataOut != NULL,"mxGetDoubles(pMxDataPropertyOut) failed");

for (size_t i = 0; i < numberOfElements; i++)
    pDataOut[i] = pDataIn[i] * 2.0;

You set the data property of plhs[0] to pMxDataPropertyOut (when all of the double values are still 0.0), and THEN you modify the data of pMxDataPropertyOut! But at that point pMxDataPropertyOut is not related to plhs[0] whatsoever, because a DEEP copy of it was put into plhs[0], not a shared data copy. You need to reverse the order of these statements and modify pMxDataPropertyOut before you put a deep copy of it into plhs[0]. E.g.,

pDataOut = mxGetDoubles(pMxDataPropertyOut);
MEXASSERT(pDataOut != NULL,"mxGetDoubles(pMxDataPropertyOut) failed");
for (size_t i = 0; i < numberOfElements; i++) // modify the data first!
    pDataOut[i] = pDataIn[i] * 2.0;
mxSetProperty(plhs[0],0,"data",pMxDataPropertyOut); // then deep copy to plhs[0]

Again, this behavior is different from the treatment of cell and struct arrays in a mex routine. Cell and struct arrays work with shallow copies of the elements, and classdef objects work with deep copies of the properties (with the potential caveat noted above).

[AJ]

Thank you for enlightening; I'm fortunate that you chose to respond.

I see now in the help for mxSetProperty:

"mxSetProperty makes a copy of the value before assigning it as the new property value. If the property uses a large amount of memory, then making a copy might be a concern. There must be sufficient memory in the heap to hold the copy of the value."

Likewise, "mxGetProperty makes a copy of the value."

I've been writing mex functions for 32 years, which just goes to show that there's always something more to learn!