Architecture Note: Integrating C Code with Wolfram Language via LibraryLink

Requirements

To use LibraryLink you need Mathematica 11.0 or later and a supported C compiler: GCC on Linux, Clang on macOS, or Visual Studio on Windows. The compiler version must match the one used to build the Mathematica distribution; mismatched ABIs can cause silent misbehavior. Your source must implement the LibraryLink API, including the mandatory initialization and uninitialization entry points.

Smallest Suitable Design

A minimal LibraryLink project consists of one C file that exports a single function and registers it through WolframLibrary_setLibraryFunctions. The function signature follows the pattern:

int addTwo(WolframLibraryData libData, mint Argc, MArgument *Args, MArgument Res)

This example receives two integers, computes their sum, and stores the result in Res. On the Mathematica side you load the compiled library with LibraryFunctionLoad, specifying the library path, function name, argument types, and return type. The resulting Wolfram Language function behaves like any built-in function.

Trust and Data Boundaries

LibraryLink enforces a copy-by-value boundary between the kernel and native code. Arguments are marshaled into managed buffers; the C function receives opaque MArgument handles and must use WolframLibraryData accessor functions to read or write data. The kernel never exposes raw pointers to its internal expression tree, so a buggy or malicious native function cannot corrupt kernel memory directly. Shared-memory passing is opt-in and requires explicit use of MTensor with the LIBRARY_NUMERICAL flag.

Operational Checks

Before each call, Mathematica validates argument types and ranks against the signature declared in LibraryFunctionLoad. After execution it inspects the integer return code: zero indicates success; non-zero values map to LibraryFunctionError messages. Developers should use WolframLibraryData functions such as MTensor_new and MTensor_free for any heap allocation inside the C function to ensure the kernel can track and reclaim memory.

Failure Modes

• Type mismatch: Passing a real where an integer is expected triggers a kernel error message rather than a crash, but mismatched tensor ranks can still cause undefined behavior if the C code assumes a fixed layout.
• Memory leaks: Failing to free MTensor buffers allocated with MTensor_new leaks kernel memory across evaluations.
• Compiler incompatibility: Linker errors or runtime crashes often stem from using a compiler version not listed in the Mathematica documentation for your platform.
• Concurrency hazards: Global or static state in the C code is shared across kernel threads. Parallel evaluations (e.g., ParallelMap) can invoke the same library function concurrently, so any mutable global data must be thread-local or protected by a mutex.

Design Change Triggers

Revise the integration when:

• Wolfram releases a new LibraryLink version that breaks ABI compatibility (major version bump).
• The target platform drops support for the required compiler toolchain.
• Performance profiling shows excessive marshaling overhead; consider shared-memory MTensor or batching multiple operations into a single call.
• Security policy changes require sandboxing native code; LibraryLink runs in-process, so a separate process with WSTP may become necessary.

Verification Checklist

1. Compile the example project from the official documentation with the exact compiler version recommended for your Mathematica installation.
2. Load the library via LibraryFunctionLoad and test a range of inputs, including edge cases (empty tensors, large arrays, mixed numeric types).
3. Inspect exported symbols with nm -D (Linux/macOS) or dumpbin /exports (Windows) to confirm the expected function signature is present.
4. Trigger error paths (wrong argument count, invalid tensor rank) and verify that LibraryFunctionError messages appear instead of kernel crashes.