Introduction

Most modern computer systems provide ways to collect code into libraries. These libraries are said to be dynamic if they can be loaded into an application at runtime rather than when the application is built. If loading can happen after an application has already started running, it is a particularly useful way to add functionality. Many plug-in architectures are built from dynamic libraries that are loaded in this way.

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.

You can load a function from a Wolfram Library into Mathematica with LibraryFunctionLoad.

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

You call the LibraryFunction, giving it an integer argument; the result is also an integer.

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

You can use the function inside a table or other Mathematica programming structure.

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

If you call the function with an input that is not an integer, then an error results and the input is returned unchanged.

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

One way to create a Wolfram Library is to write it in C or C++ and use C development tools. Here is the source for the function (the details of the C code are explained in the section "Library Structure and Life Cycle").

DLLEXPORT int demo_I_I(WolframLibraryData libData, 
                mint Argc, MArgument *Args, MArgument Res) {
    mint I0;
    mint I1;
    I0 = MArgument_getInteger(Args[0]);
    I1 = I0 + 1;
    MArgument_setInteger(Res, I1);
    return 0;
}

In addition to passing machine integers, a number of other formats can be passed.

machine integersmachine reals
machine complexespacked arrays
stringsgeneral expressions

Alternatives to Wolfram Library Functions

Loading functions directly from a Wolfram Library has a number of advantages and disadvantages. This section reviews the advantages and disadvantages and discusses alternatives.

Mathematica

One alternative is to use Mathematica. This means writing code in the normal way for programming Mathematica. Following is a summary of the advantages and disadvantages.

  • Mathematica code is faster to write and does not need to be compiled for each platform on which it is run.
  • Mathematica code automatically collects memory when it is not used.
  • Mathematica code runs in a safe mode; you cannot crash a Mathematica program from a programmer error in the way that a C function can crash.
  • A library function can in certain cases be faster than one written in Mathematica. Writing core functions in a library is one way to improve performance of your application. Of course, if your application calls many core functions such as matrix manipulation, these are already very optimized in Mathematica.
  • If you want to interact with another library, it can be convenient and efficient to call it from a library.

MathLink Applications

Another alternative is to use MathLink. This means writing code as a C program and connecting to Mathematica using the MathLink programming interface. Following is a summary of the advantages and disadvantages.

  • MathLink applications typically run in a separate process so if the MathLink program crashes Mathematica is not affected.
  • The MathLink interface allows any Mathematica expression to be written to and read from an application. However, you can also use MathLink to communicate with a library function. So this is not really an advantage or disadvantage.
  • The MathLink interface supports running Mathematica and the MathLink application on different machines, perhaps running different types of systems.
  • The overhead to calling a library function is much lower than using the MathLink interface.
  • Arguments passed to and from a library function can share data, saving on memory consumption and the time to copy large amounts of data.
  • When Mathematica is waiting for a MathLink application to return a result, it can be used to service preemptive computations such as those needed for user interface operations. When a library function is running this will not happen without effort by the author of the library.
  • A library function will stop running if the host Mathematica process stops running. It is not always guaranteed that a MathLink application will terminate when Mathematica terminates.
  • The MathLink allows you to connect 32- and 64-bit applications together. A library must be binary compatible with the Mathematica in which it is running.
New to Mathematica? Find your learning path »
Have a question? Ask support »