Examples

Wolfram LibraryLink allows dynamic libraries to be directly loaded into the Mathematica kernel so that functions in the libraries can be immediately called from Mathematica. You can exchange not only C-like data types such as integers, reals, packed arrays, and strings, but also arbitrary Mathematica expressions. In addition, there are useful functions such as sending errors and calling back to Mathematica.

A number of sample Wolfram Libraries are included with the documentation. These have a number of short functions that demonstrate various aspects of calling libraries from Mathematica.

Using the Examples

The documentation contains the source for the sample libraries. You will need access to a C compiler to build the libraries, and you might find the CCompilerDriver package useful.

This shows that the demo example can be found for your platform.

In[1]:=
Click for copyable input
Out[1]=

This loads a function from the demo example library.

In[2]:=
Click for copyable input
Out[2]=

This calls the function.

In[3]:=
Click for copyable input
Out[3]=

Source

The source for the examples is found in the documentation paclet. You can find this by evaluating the following input.

In[4]:=
Click for copyable input
Out[4]=
demo.csample of basic examples
demo_shared.csample of basic examples of shared passing
demo_error.csample of error catching
demo_string.csample of using string arguments and results
demo_mathlink.csample of using LinkObject as an argument and result specification

Library examples source files.

demo

The demo example contains many functions; here is an example of using it.

In[5]:=
Click for copyable input
Out[6]=

demo_shared

The demo_shared example has an example of sharing a packed array with a library function. The following loads a number of functions.

In[7]:=
Click for copyable input

This creates a packed array and loads it into the library. Since shared memory passing was used, the array can be used in other function calls.

In[10]:=
Click for copyable input
Out[11]=

This gets the 10^(th) element, which is 10.

In[12]:=
Click for copyable input
Out[12]=

This unloads the array; after this the array cannot be used any more.

In[13]:=
Click for copyable input
Out[13]=

This shows the source of some of the functions.

DLLEXPORT int loadArray(WolframLibraryData libData,
            mint Argc, MArgument *Args, MArgument Res) {

    tensor = MArgument_getMTensor(Args[0]);
    MArgument_setInteger(Res, 0);
    return LIBRARY_NO_ERROR;
}

DLLEXPORT int getElementVector(WolframLibraryData libData,
            mint Argc, MArgument *Args, MArgument Res) {
    mint pos;
    double value;
    
    pos = MArgument_getInteger(Args[0]);
    value = libData->MTensorVector_getReal( tensor, pos);
    
    MArgument_setReal(Res, value);
    return LIBRARY_NO_ERROR;
}

DLLEXPORT int unloadArray(WolframLibraryData libData,
            mint Argc, MArgument *Args, MArgument Res) {

    libData->MTensor_disown( tensor);
    MArgument_setInteger(Res, 0);
    return LIBRARY_NO_ERROR;
}

demo_error

The demo_error example has examples of calling functions that trigger errors. The following loads a function from the library.

In[14]:=
Click for copyable input

This is the source of the errordemo1 function. It takes an MTensor argument and then tries to get the real data.

DLLEXPORT int errordemo1(WolframLibraryData libData,
            mint Argc, MArgument *Args, MArgument Res) {
    MTensor T0, T1;
    mint I0, I1, res;
    mint pos[2];
    double *data;

    T0 = MArgument_getMTensor(Args[0]);
    I0 = MArgument_getInteger(Args[1]);
    
    data = libData->MTensor_getRealData(T0);
    MArgument_setReal(Res, data[I0]);
    return LIBRARY_NO_ERROR;
}

The example takes an integer MTensor. The function calls MTensor_getRealData which results in an error and returns a LibraryFunctionError expression.

In[15]:=
Click for copyable input
Out[15]=

demo_string

The demo_string example shows some ways that you can use string arguments and results with the required memory management. The following loads a function that does a simple shift cipher for an ASCII string.

In[17]:=
Click for copyable input

This is the source of the encoding function. The arguments are the string to encode and the integer shift to apply.

DLLEXPORT int encodeString(WolframLibraryData libData,
        mint Argc, MArgument *Args, MArgument Res)
{
    mint i = 0, shift;
    
    if (string)
        libData->String_disown(string);

    string = MArgument_getUTF8String(Args[0]);
    shift = MArgument_getInteger(Args[1]);

    /* Find shift mod 127 so we only
     deal with positive numbers below */
    shift = shift % 127;
    if (shift < 0)
        shift += 127;

    shift -= 1;
        
    while (string[i]) {
        mint c = (mint) string[i];
        /* Error for non ASCII string */
        if (c & 128) return LIBRARY_FUNCTION_ERROR;
        c = ((c + shift) % 127) + 1;
        string[i++] = (char) c;
    }
    MArgument_setUTF8String(Res, string);
    return LIBRARY_NO_ERROR;
}

Here is an example.

In[18]:=
Click for copyable input
Out[18]=

Note that the string reference is stored in a variable with scope outside of the function. This reference is disowned when either the function is called again (and a new string is referenced) or when the library is unloaded (in the function WolframLibrary_uninitialize). Since the string argument memory is owned entirely by the library functions, the encoding can be done in place in that memory, saving the need to allocate another string.

demo_mathlink

The demo_mathlink example shows using LinkObject as an argument and result specification. The following loads a function from the library.

In[19]:=
Click for copyable input

This is the source of the reverseString function. It takes an MLINK argument and uses the MathLink API to read the arguments that come in a list. After it has generated the result, this is written onto the link.

DLLEXPORT int reverseString( WolframLibraryData libData, MLINK mlp)
{
    int res = LIBRARY_FUNCTION_ERROR;
    long len;
    const char *inStr = NULL;
    char* outStr = NULL;
    
    if ( !MLCheckFunction( mlp, "List", &len))
        goto retPt;
    if ( len != 1)
        goto retPt;

    if(! MLGetString(mlp, &inStr))
        goto retPt;

    if ( ! MLNewPacket(mlp) )
        goto retPt;

    outStr = reverseStringImpl(inStr);
    
    if (!MLPutString( mlp,outStr))
        goto retPt;
    res = 0;
retPt:
    if ( inStr != NULL)
        MLReleaseString(mlp, inStr);
    if ( outStr != NULL)
        free( (void*) outStr);
    return res;
}

Here we pass in a string. The result is read from the link and displayed.

In[20]:=
Click for copyable input
Out[20]=
New to Mathematica? Find your learning path »
Have a question? Ask support »