Tech docs for mexlib
the stuff you think we should know
I did a good progress with mexlib but it is not done. Some tests are broken and some functions added in last mex specification are not implemented. All not implemented functions are declared at the end of mex.h file or marked with FIXME or TODO comments in mexlib.cpp.
I implemented memory management just calling standard memory functions (e.g. mxMalloc just call MALLOC), I don't know if it is right, maybe it has some memory leaks. This implementation do mexMakeMemoryPersistent useless.
Some important things:
- String matrices in Scilab are Mx1 instead MxN (like in MATLAB);
- Scilab types didn't handle complex values. Only double has an imaginary part. Because of it, functions like mxGetPi and mxGetImagData are equivalent (get imaginary data from double data), but mxGetImagData is defined to get
Sparse types are not implemented yet in YaSp, neither any mexlib function handling sparses.
Known bugs
My known bugs are broken tests. I describe it below.
What should be done next?
We should implement remained functions and test it with real mexlib files.
Is it a version 0.1 or 1.0?
It is something lika an alpha version. Some functions are not implemented yet. I guess it is an usable version, but only an early adopter will do that.
How many unitary tests? Where are they?
All mexlib tests are in mexlib module. To run then:
unit_test_run("mexlib", [], "no_check_error_output")
I have 67 unit tests, but 3 are broken.
Tests broken are:
- mxSetClearLogical: tests to mxSetLogical and mxClearLogical. These functions are obsolete. My mxSetLogical implementation handle only conversion from int32 to logical.
mexAtExit: I just wrote the test, but I don't know how to execute a function after mexFunction. I guess it need some changes in WrapMexFunction in function type.
- mexFunctionName: I just wrote the test, I don't know how to get function name.
Are you planning to implement what is missing?
Most part of what I didn't implemented, Bruno JOFRET and Allan CORNET will work on it, because it isn't an easy task. I won't have time in next months to work on it, because I'm late with my graduation project.
Are you planning to maintain it in the future?
I liked mexlib and Scilab and want to maintain it in the future, but for now I can't because of my spare time in next months. Maybe work in other parts of Scilab too.
Which mexlib functions are implemented?
Types defined: mxLogical, mxArray, mxChar, mxClassID, mxComplexity, mwSize, mwIndex, mwSignedIndex, mwPointer
These functions should work like specified. They are implemented and tested:
mexCallMATLAB
mexCallSCILAB (equivalent to mexCallMATLAB)
mexErrMsgTxt
mexEvalString
mexGetArray (obsolete)
mexGetVariable
mexGetVariablePtr
mexIsGlobal
mexPrintf
mexPutFull (obsolete)
mexPutVariable
mexWarnMsgTxt
mxAddField
mxArrayToString
mxAssert
mxAssertS
mxCalcSingleSubscript
mxClearLogical (obsolete)
mxCreateCellArray
mxCreateCellMatrix
mxCreateCharArray
mxCreateCharMatrixFromStrings
mxCreateDoubleMatrix
mxCreateDoubleScalar
mxCreateLogicalArray
mxCreateLogicalMatrix
mxCreateLogicalScalar
mxCreateNumericArray
mxCreateString
mxCreateStruct
mxDestroyArray
mxDuplicateArray
mxFreeMatrix (obsolete)
mxGetChars
mxGetClassID
mxGetClassName
mxGetDimensions
mxGetElementSize
mxGetEps
mxGetField
mxGetFieldByNumber
mxGetFieldNameByNumber
mxGetInf
mxGetLogicals
mxGetNaN
mxGetNumberOfDimensions
mxGetNumberOfElements
mxGetNumberOfFields
mxGetData
mxGetM
mxGetN
mxGetPr
mxGetPi
mxGetString
mxIsCell
mxIsChar
mxIsClass
mxIsComplex
mxIsDouble
mxIsEmpty
mxIsFinite
mxIsFunction
mxIsInf
mxIsInt8
mxIsInt16
mxIsInt32
mxIsInt64
mxIsLogical
mxIsLogicalScalar
mxIsLogicalScalarTrue
mxIsNaN
mxIsSingle
mxIsStruct
mxIsUint8
mxIsUint16
mxIsUint32
mxIsUint64
mxSetCell
mxSetDimensions
mxSetField
mxSetFieldByNumber
mxSetData
mxSetM
mxSetN
mxSetPr
mxSetPi
Some functions are implemeneted but not really tested or with some known issue:
mxMalloc, mxCalloc, mxRealloc, mxFree: these functions just call MALLOC, CALLOC, REALLOC and FREE functions.
mxGetImagData, mxSetImagData: it is tested only for double type, because other Scilab types don't have an imaginary part.
mxSetLogical: obsolete, it works only with a int32 mxArray, constructing a new logical mxArray based on the original. Has skipped tests.
mxGetScalar: this function is defined to return first nonzero real element in mxArray, but it is implemented to return first value, even if it is zero.
Functions not implemented:
mexAtExit: has skipped tests, but is not implemented.
mexFunctionName: has skipped tests, but is not implemented.
mexMakeMemoryPersistent
mexMakeArrayPersistent
mxGetProperty
mxSetProperty
mxIsFromGlobalWS
mxRemoveField
mxSetClassName
mexCallMATLABWithTrap
mexEvalStringWithTrap
mexSetTrapFlag
mexErrMsgIdAndTxt
mexGet
mexWarnMsgIdAndTxt
mexSet
mexIsLocked
mexLock
mexUnlock
mxCreateSparseLogicalMatrix
mxGetJc, mxSetJc, mxGetIr, mxSetIr, mxGetNzmax, mxSetNzmax, mxIsSparse: sparse types aren't implemented. const char *mxGetName(const mxArray *array_ptr);
mxGetName, mxSetName: obsolete, it is declared in old mexlib but not implemented.
Functions marked as obsolete are maintained in Scilab for backward compatibility with old mex versions, but these functions are removed from last mex specs.