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 Wolfram Language kernel so that functions in the libraries can be immediately called from the Wolfram Language. You can exchange not only C-like data types such as integers, reals, packed arrays, and strings, but also arbitrary Wolfram Language expressions. In addition, there are useful functions such as sending errors and calling back to the Wolfram Language.

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

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

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

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

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, including machine reals and complexes, strings, packed arrays, sparse arrays, numeric arrays, images, and general 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.

The Wolfram Language

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

• Wolfram Language code is faster to write and does not need to be compiled for each platform on which it is run.

• Wolfram Language code automatically collects memory when it is not used.

• Wolfram Language code runs in a safe mode; you cannot crash a Wolfram Language 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 the Wolfram Language. 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 the Wolfram Language.

• If you want to interact with another library, it can be convenient and efficient to call it from a library.

WSTP Applications

Another alternative is to use the Wolfram Symbolic Transfer Protocol (WSTP). This means writing code as a C program and connecting to the Wolfram Language using the WSTP programming interface. Following is a summary of the advantages and disadvantages.

• WSTP applications typically run in a separate process so if the WSTP program crashes the Wolfram Language is not affected.

• The WSTP interface allows any Wolfram Language expression to be written to and read from an application. However, you can also use WSTP to communicate with a library function. So this is not really an advantage or disadvantage.

• The WSTP interface supports running the Wolfram Language and the WSTP application on different machines, perhaps running different types of systems.

• The overhead to calling a library function is much lower than using the WSTP 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 the Wolfram Language is waiting for a WSTP 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 Wolfram Language process stops running. It is not always guaranteed that a WSTP application will terminate when the Wolfram Language terminates.

• The WSTP allows you to connect 32- and 64-bit applications together. A library must be binary compatible with the Wolfram System in which it is running.