LibraryLink Documentation

Question

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;
}

Answer 1

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".