12
$\begingroup$

Bug fixed in version 10.0.0


The documentation for LibraryLink has the following example

DLLEXPORT int demo_TI_R(WolframLibraryData libData,
 mint Argc, MArgument *Args, MArgument Res) {
 MTensor T0;
 mint I0;
 double R0;
 T0 = MArgument_getMTensor(Args[0]);
 I0 = MArgument_getInteger(Args[1]);
 R0 = libData->MTensorVector_getReal(T0, I0);
 MArgument_setReal(Res, R0);
return LIBRARY_NO_ERROR;
}

I am trying to figure out what the command MTensorVector_getReal does. This looks like it is undocumented.

Similarly, in the following example from the documentation, it is not clear what funStruct is, and where it is coming from. Should it be libData instead?

DLLEXPORT int demo1_TI_R(WolframLibraryData libData,
 mint Argc, MArgument *Args, MArgument Res) {
 MTensor T0;
 mint I0;
 double R0;
 T0 = MArgument_getMTensor(Args[0]);
 I0 = MArgument_getInteger(Args[1]);
 R0 = funStruct->MTensorVector_getReal( T0, I0);
 libData->MTensor_free(T0);
MArgument_setReal(Res, R0);
return LIBRARY_NO_ERROR;
}
$\endgroup$
3

1 Answer 1

14
$\begingroup$

My advice is to not rely on the code samples in the documentation. It has proven to be unreliable. For instance

  • In the documentation to MTensor_getComplexData the example doesn't even use the function.
  • The documentation to MTensor_free can barely be called documentation since it does not explain about memory allocation etc
  • The documentation to AbortQ states that this function returns a mystical TRUE value, where the definitions in "WolframLibrary.h" clearly shows that it is #define True 1

These things and the undocumented function you found are only some of the small mistakes/typos you find around the WolframLibrary documentation.

Regarding your two questions

I can only guess to answer your questions. I believe

double MTensorVector_getReal(MTensor t, mint pos)

is equivalent to

int MTensor_getReal(MTensor t, mint *pos, mreal *res)

with the difference that it is specifically made for rank 1 tensors. The advantage is that you can simply pass an integer as position and not a pointer and you get the result directly back from the function. The only reference I found in all *.m or *.c files is in CodeGenerator.m located in

FileNames["CodeGenerator.m", {$InstallationDirectory}, 4]
(* 
 {"/Applications/Development/Mathematica.app/SystemFiles/Links/GPUTools/CodeGenerator.m"}
*)

So this function was probably planned to make it to the final WolframLink API but didn't in the end.

I couldn't find this function in neither the header files or the libWolframRTL so it seems you cannot use it in version 9.0.1!

Regarding the funStruct in your second example, there is a similar thing in compiled functions which are converted to C code. A simple example is the following

<< CCodeGenerator`;
CCodeStringGenerate[Compile[{}, 1], "fun"]

When you examine the created code you see that it has a static variable funStructCompile which is used in an equivalent way as in your example. I assume the funStruct in your example is a typo.

Further reading

As I said in the beginning, although the documentation (especially the WolframLibrary tutorial) gives insight into the usage, I would not count on that code blocks are up to date.

I would recommend that you look into the example files you find here

FileNames["demo*.c", {$InstallationDirectory}, Infinity]

There you find the correct versions of the functions demo_TI_R and demo1_TI_R in "demo.c".

$\endgroup$
5
  • $\begingroup$ Thanks for this. I am not sure whether double MTensorVector_getReal(MTensor t, mint pos) really exists. Will wait a bit before accepting. $\endgroup$
    – asim
    Aug 6, 2013 at 3:53
  • $\begingroup$ @asim have you tried running it? If there are no errors, than it exists, otherwise ... $\endgroup$
    – rcollyer
    Aug 6, 2013 at 4:09
  • 1
    $\begingroup$ @halirutan, I filed the 3 issues as bugs against the documentation. Should there be more, just send them to [email protected]. Thanks. $\endgroup$
    – user21
    Aug 6, 2013 at 6:14
  • $\begingroup$ @asim It seems MTensorVector_getReal doesn't exist in neither the header files nor the library itself. I'll check older versions of Mathematica when I have time. There must be some more references anywhere. $\endgroup$
    – halirutan
    Aug 6, 2013 at 8:56
  • $\begingroup$ @halirutan I am trying to learn library link these days. Just as you said, the official documentation sucks, and also my IQ. I just got errors and errors, when I write on my own. Do you have good resources which can make the learning not such painful? :) $\endgroup$
    – matheorem
    Jan 3, 2016 at 7:45

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.