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 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.
Foreign Function Interface »
The Foreign Function Interface (FFI) allows you to call functions from C-compatible dynamic libraries directly from Wolfram Language. Following is a summary of the advantages and disadvantages.
- It is commonly the case that the user will have to make use of low-level functionality like memory allocation, pointers, etc., when using the FFI. Naive usage of these functions might result in inefficient handling of memory or could even cause crashes.
The Wolfram Compiler »
A lower level alternative is to use the Wolfram Compiler. This means writing Wolfram Language code and compiling it into efficient native machine code. Following is a summary of the advantages and disadvantages.
- The Wolfram Compiler allows existing Wolfram Language code to be optimized for high-speed and memory-efficient execution by compiling it into native machine code.
- The Wolfram Compiler can generate executable code suitable not only for internal use by the Wolfram System, but also for linking into external programs.
- The Wolfram Compiler has an advanced type inferencing that allows types to be inferred automatically or specified in minimal ways by users.
- Not all Wolfram Language code can be currently compiled. This downside can be avoided by invoking the Wolfram Language Kernel inside compiled code in order to execute the unsupported functionality.
- Presently, compilation of certain Wolfram Language code can be slow. However, once the code has been compiled, e.g. into a library, execution is extremely fast. The Wolfram Compiler is being actively developed to overcome this drawback.
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.
- 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.