ForeignFunctionLoad
ForeignFunctionLoad[lib,fun,{argtype1,argtype2,…}rettype]
loads the function fun with the specified argument and output types from the library lib.
ForeignFunctionLoad[ptr,{argtype1,argtype2,…}rettype]
creates a foreign function from the function pointer ptr.
Details
- ForeignFunctionLoad returns the ForeignFunction object.
- lib is resolved with FindLibrary.
- lib must be a C-compatible dynamic library.
- Supported types generally align with those supported by the Wolfram Compiler.
- Possible argument and return types and their corresponding C types include:
-
"UnsignedInteger8" uint8_t unsigned 8-bit integer "Integer8" int8_t signed 8-bit integer "UnsignedInteger16" uint16_t unsigned 16-bit integer "Integer16" int16_t signed 16-bit integer "UnsignedInteger32" uint32_t unsigned 32-bit integer "Integer32" int32_t signed 32-bit integer "UnsignedInteger64" uint64_t unsigned 64-bit integer "Integer64" int64_t signed 64-bit integer "CUnsignedChar" unsigned char C-compatible unsigned char "CSignedChar" signed char C-compatible signed char "CUnsignedShort" unsigned short C-compatible unsigned short "CShort" short C-compatible short "CUnsignedInt" unsigned int C-compatible unsigned int "CInt" int C-compatible int "CUnsignedLong" unsigned long C-compatible unsigned long "CLong" long C-compatible long "CSizeT" size_t C-compatible size_t "CFloat" float C-compatible float "CDouble" double C-compatible double "OpaqueRawPointer" void* opaque pointer "RawPointer"::[t] t* typed pointer {ty1,ty2,…} struct {ty1 f1; ty2 f2; …} struct or product type "Void" void no output (only in output types) - Struct or product types can also be written as "ListTuple"::[ty1,ty2, …].
- In ForeignFunctionLoad[ptr,…], ptr must be an OpaqueRawPointer pointing to a valid function in a library.
Examples
open all close allBasic Examples (1)
Scope (2)
ForeignFunctionLoad uses FindLibrary to locate libraries:
ForeignFunctionLoad["compilerDemoBase", "addone", {"CInt"} -> "CInt"]Alternatively, find the library once with FindLibrary and pass it to ForeignFunctionLoad:
lib = FindLibrary["compilerDemoBase"];
ForeignFunctionLoad[lib, "addone", {"CInt"} -> "CInt"]Get the pointer to a function in a library:
funPtr = ForeignPointerLookup["compilerDemoBase", "addone"]Load the foreign function by using the function pointer and specifying its type:
ForeignFunctionLoad[funPtr, {"CInt"} -> "CInt"]Applications (2)
Create a foreign function for the RAND_bytes function from OpenSSL:
opensslPath = FileNameJoin[...];randBytes = ForeignFunctionLoad[opensslPath, "RAND_bytes", {"RawPointer"::["UnsignedInteger8"], "CInt"} -> "CInt"]Create a buffer into which the random bytes can be written:
out = RawMemoryAllocate["UnsignedInteger8", 32]Generate the random bytes by calling RAND_bytes:
randBytes[out, 32]RawMemoryImport[out, {"List", 32}]generateRandomBytes[len_] :=
With[{out = RawMemoryAllocate["UnsignedInteger8", len]},
randBytes[out, len];RawMemoryImport[out, {"ByteArray", len}]
]The foreign function is very efficient:
RepeatedTiming[generateRandomBytes[10000000];]RepeatedTiming[RandomInteger[{0, 255}, 10000000];]Implement SHA256 using OpenSSL:
opensslPath = FileNameJoin[...];sha256 = ForeignFunctionLoad[opensslPath, "SHA256", {"RawPointer"::["UnsignedInteger8"], "CUnsignedLong", "RawPointer"::["UnsignedInteger8"]} -> "RawPointer"::["UnsignedInteger8"]]Create a buffer containing the plaintext to hash:
plaintext = "Hello, World!";
plaintextBuf = RawMemoryExport[plaintext]Create a buffer into which to write the hash:
ciphertextBuf = RawMemoryAllocate["UnsignedInteger8", 32]sha256[plaintextBuf, StringLength[plaintext], ciphertextBuf]Read the results from the ciphertext buffer:
RawMemoryImport[ciphertextBuf, {"List", 32}]Compare with the built-in function Hash:
Normal@Hash[plaintext, "SHA256", "ByteArray"]generateSHA256[plaintext_] :=
With[{
plaintextBuf = RawMemoryExport[plaintext], ciphertextBuf = RawMemoryAllocate["UnsignedInteger8", 32]
},
sha256[plaintextBuf, StringLength[plaintext], ciphertextBuf];
RawMemoryImport[ciphertextBuf, {"ByteArray", 32}]
]The packaged function is very efficient:
RepeatedTiming[generateSHA256[plaintext]]RepeatedTiming[Hash[plaintext, "SHA256", "ByteArray"]]Properties & Relations (1)
ForeignFunctionLoad can generally create callable links to libraries faster than custom links can be compiled:
With[{libPath = FindLibrary["compilerDemoBase"]},
RepeatedTiming[addone = ForeignFunctionLoad[libPath, "addone", {"CInt"} -> "CInt"]]
]RepeatedTiming[addoneCf = FunctionCompile[
LibraryFunctionDeclaration["addone", "compilerDemoBase", {"CInt"} -> "CInt"],
Function[Typed[x, "CInt"], LibraryFunction["addone"][x]]
]]However, the custom compiled versions can have less overhead:
RepeatedTiming[addone[10]]RepeatedTiming[addoneCf[10]]Possible Issues (3)
If the library does not exist, a Failure is returned:
ForeignFunctionLoad["fakeLibrary", "addone", {"CInt"} -> "CInt"]
If the function does not exist, a Failure is returned:
ForeignFunctionLoad["compilerDemoBase", "fakeFunction", {"CInt"} -> "CInt"]
ForeignFunctionLoad will return $Failed if a type is not supported:
ForeignFunctionLoad["compilerDemoBase", "addone", {"UnsignedInger18"} -> "CInt"]
Text
Wolfram Research (2023), ForeignFunctionLoad, Wolfram Language function, https://reference.wolfram.com/language/ref/ForeignFunctionLoad.html.
CMS
Wolfram Language. 2023. "ForeignFunctionLoad." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/ForeignFunctionLoad.html.
APA
Wolfram Language. (2023). ForeignFunctionLoad. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/ForeignFunctionLoad.html