Library Structure and Life Cycle
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.This section describes the structure of a Wolfram Library and how they are written. It also covers the different parts of the life cycle of a library, from initialization through usage to uninitialization.
The first time that a function is loaded from a Wolfram Library with
LibraryFunctionLoad, its
initialization function is called. This sets up a structure to support callback functions; it can also be used to carry out any initialization specific to the library itself.
Once a library has been loaded, you can call its functions through the
LibraryFunction returned by
LibraryFunctionLoad. You can also load additional functions.
When the library is no longer required it can be unloaded. This happens when all the functions are unloaded with
LibraryFunctionUnload, or when the entire library is unloaded with
LibraryUnload. At this point the
uninitialize function is called.
Note that unloading a library completely is not supported on all platforms. The
uninitialize function will always be called and functions from the library will not be usable from
Mathematica. However, only platforms that fully support dynamic library unloading will let you modify the library and then reload it. When this documentation was written, Windows and Mac OS X 10.5 fully supported unloading a library.
Initialization
When a library is loaded for the first time using
LibraryFunctionLoad, some important initialization is carried out. This sets up the structure that allows the library function to call back to
Mathematica; it also takes care of versioning. The library allows initialization by providing a function called
WolframLibrary_initialize. Typically, the first part of the library is similar to that shown below.
#include "WolframLibrary.h"
DLLEXPORT mint WolframLibrary_getVersion( ) {
return WolframLibraryVersion;
}
DLLEXPORT int WolframLibrary_initialize( WolframLibraryData libData) {
return 0;
}
Here the header
"WolframLibrary.h", which sets up various important definitions, is loaded. This is followed by the function
WolframLibrary_getVersion, which returns the version of the WolframLibrary header.
Mathematica then calls
WolframLibrary_initialize, passing in a data structure that matches the version of the WolframLibrary header used to build the library. Since the function structure is adapted for your library, this means that you do not have to recompile your library when it is loaded into a new version of
Mathematica. However, you should note that you cannot use a library built with a newer version of the header into an older version of
Mathematica. The
WolframLibrary_initialize function can contain other initializations that you might need to run functions in the library. If it returns a nonzero value, that will be considered a fatal error and the library file will not be loaded.
If your library is going to use
MathLink for communicating with
Mathematica, the
"mathlink.h" header must be included before the
"WolframLibrary.h" header. This is shown below.
#include "mathlink.h"
#include "WolframLibrary.h"
Functions, Arguments, and Results
The library provides functions that are called from
Mathematica. These functions are named in the call to
LibraryFunctionLoad. Because the interface uses C calling conventions, each function has to have the same signature, namely
int demoI_I(WolframLibraryData libData, mint Argc, MArgument *Args, MArgument Res). A sample is shown below.
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 LIBRARY_NO_ERROR;
}
MArgument is a typedef for a union of pointers of the supported basic types defined in WolframLibrary.h.
typedef union {
mbool *boolean;
mint *integer;
double *real;
mcomplex *cmplex;
MTensor *tensor;
char **utf8string;
} MArgument;
The function must have the signature
int demo_I_I(mint Argc, MArgument *Args, MArgument Res), it must return
int, and must take three arguments. The first is a machine integer giving the argument count, the second is an array of
MArgument, and the third is an
MArgument. These hold the input and the result, respectively. You have to extract the actual value from the argument array and assign the result. Several macros with names starting with
MArgument are defined for convenience for this extraction and assignment to
MArgument. The returned int value returned is used as an error code: any nonzero return will be considered an error and the evaluation will return a
LibraryFunctionError result. More details about error codes are found in the section
"Error Result Codes".
More details about how to work with types are found in the section
"Type Specification".
In addition, it is typical to add
DLLEXPORT; this is a macro defined in WolframLibrary.h. It is needed on Windows where it declares the function as an export from a Windows DLL, but using it will make your library easier to move from one platform to another.
If you want to send arguments or get results from the library function that are not covered by the basic numerical types or an
MTensor, you can use a
LinkObject for arguments and the result. This will let you send the structure of any
Mathematica expression to your library and get back any
Mathematica expression as a result. A sample
LinkObject function is shown below. Note that you can work directly with strings without using
MathLink.
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 = LIBRARY_NO_ERROR
retPt:
if ( inStr != NULL)
MLReleaseString(mlp, inStr);
if ( outStr != NULL)
free((void*)outStr);
return res;
}
To use
MathLink for communicating with
Mathematica, the
"mathlink.h" header must be included before the
"WolframLibrary.h" header.
More information on using
MathLink to communicate with
Mathematica is found in the section
LinkObject Arguments and Result.
Naming Conventions
Note that the name of the function is used to load it into
Mathematica. If you compile your library as C++ then you will either have to export the name as a C name or use the C++ modified name in
LibraryFunctionLoad. The former can be done by a declaration such as the following.
extern "C" {
DLLEXPORT int funname(WolframLibraryData libData,
mint Argc, MArgument *Args, MArgument Res);
}
This makes sure that
funname can be used to load the function even though the library is compiled as C++.
Alternatively, you can use a macro defined in WolframLibrary.h to make the code more portable.
EXTERN_C DLLEXPORT int funname(WolframLibraryData libData,
mint Argc, MArgument *Args, MArgument Res);
Types
In your library function you can use any types that you want, except for arguments from
Mathematica and results that go to
Mathematica. These are described below.
| mbool | Boolean |
| mint | machine integer |
| double | machine double |
| mcomplex | machine complex |
| MTensor | packed array |
| UTF8String | UTF8 string |
There are definitions for
mbool,
mint,
mcomplex, and
MTensor in WolframLibrary.h.
mint is an integral type that matches the machine integer type in
Mathematica; note that this might be 32 or 64 bits.
Callbacks
Often you may need extra functionality that is present in
Mathematica. For example, you might want to create a packed array and then work with its elements. This is done via the
WolframLibraryData object that is passed in as an argument to the function. In the following example, a packed array is created, and then its elements are filled in.
T0 = funStruct->MTensor_new(MType_Integer, 1, dims);
for ( i = 1; i <= I0; i++) {
libData->MTensorVector_setInteger( T0, i, i*2);
}
Callback Evaluations in Mathematica
If you want to call
Mathematica from your library function to carry out some other task, for example, carrying out some computation or calling some input/output function, you can do this with
getMathLink and
processMathLink.
The following example shows how you get a
MathLink connection and then write an expression inside
EvaluatePacket on the link using functions from the
MathLink API. When you have finished, you call
processMathLink and
Mathematica will carry out the evaluation.
MLINK link = libData->getMathLink(libData);
MLPutFunction( link, "EvaluatePacket", 1);
MLPutFunction( link, "Message", 2);
MLPutFunction( link, "MessageName", 2);
MLPutSymbol( link, "MyFunction");
MLPutString( link, "info");
MLPutString( link, "Message called from within Library function.");
libData->processMathLink( link);
pkt = MLNextPacket( link);
if ( pkt == RETURNPKT) {
MLNewPacket(link);
}
The result from
Mathematica will follow the standard packet rules for
Mathematica; for example, an
EvaluatePacket will return a result in
ReturnPacket.
Errors
If an error is found in a library function and you want to report this to a user, you can use the callback function
Message. For example, the following will cause the message
LibraryFunction
to be emitted. You would have to supply text for the message.
if (libData->MTensor_getRank(T0) != 1) {
libData->Message("rankerror");
return LIBRARY_FUNCTION_ERROR;
}
Note that returning
LIBRARY_FUNCTION_ERROR from the library will cause a
LibraryFunctionError result to be returned.
A more flexible way to send a message would be to use the c
allback evaluation technique described previously.
Error Result Codes
The result of a library function is expected to be an int and is used to determine if an error took place. If a result of 0 or
LIBRARY_NO_ERROR is returned the function is taken to have completed correctly. Alternately, if a different result is returned this indicates an error and the result of the function call is a
LibraryFunctionError expression.
There are a number of error codes that you can return. They are listed in the following table.
| LIBRARY_NO_ERROR | correct result from the function (value of 0) |
| LIBRARY_TYPE_ERROR | unexpected type encountered |
| LIBRARY_RANK_ERROR | unexpected rank encountered |
| LIBRARY_DIMENSION_ERROR | inconsistent dimensions encountered |
| LIBRARY_NUMERICAL_ERROR | error in numerical computation |
| LIBRARY_MEMORY_ERROR | problem allocating memory |
| LIBRARY_FUNCTION_ERROR | generic error from a function |
Error codes.
Each nonzero error code leads to a specific type of message being issued when the function call has finished, except for
LIBRARY_FUNCTION_ERROR, which issues no message, letting the application making the function call issue its own message.
In the following example a demonstration function is loaded. This function returns its input which lets you see the effect of different codes.
| Out[1]= |  |
This returns 6 from the library function which is the value of
LIBRARY_FUNCTION_ERROR. The result of the evaluation is a
LibraryFunctionError expression, which contains the name of the error code and its numerical value.
| Out[2]= |  |
Errors in Callbacks
If an error arises in a callback function it will return an error code.
For example, the
MTensor_getInteger callback gets an element from an
MTensor of integer type. But, if it is called on an
MTensor that does not contain integers or the element does not exist, then an error code is returned.
int err;
...
err = libData->MTensor_getInteger( T0, lens, &res);
If you are certain that the
MTensor is of the correct type and has sufficient elements then you do not need to inspect the result.
Uninitialization
When the library is no longer used by
Mathematica it will call a function to shut down the library; a sample is shown below. The function receives a
WolframLibraryData object and it can use callback functions if required.
DLLEXPORT void WolframLibrary_uninitialize( WolframLibraryData libData) {
return;
}
