ForeignFunctions -- foreign function interface

Description

This package provides the ability to load and call "foreign" functions from shared libraries and to convert back and forth between Macaulay2 things and the foreign objects used by these functions. It is powered by libffi.

As a simple example, we call the cos function from the C standard library, which sends a double (a real number represented as a double-precision floating point number) to another double, the cosine of the input.

i1 : mycos = foreignFunction("cos", double, double)

o1 = cos

o1 : ForeignFunction

i2 : mycos pi

o2 = -1

o2 : ForeignObject of type double

i3 : value oo

o3 = -1

o3 : RR (of precision 53)

In this example, we created a ForeignFunction object using the foreignFunction constructor method and specified that both its output and input were instances of the double type, which is one of several ForeignType objects that are available.

See also the following additional examples:

fast Fourier transform example -- fast Fourier transforms using foreign function calls to the FFTW library
general linear model example -- constrained least squares using foreign function calls to the LAPACK library
just-in-time compilation example -- using foreign function calls for computing Fibonacci numbers using JIT

fast Fourier transform example -- fast Fourier transforms using foreign function calls to the FFTW library
general linear model example -- constrained least squares using foreign function calls to the LAPACK library
just-in-time compilation example -- using foreign function calls for computing Fibonacci numbers using JIT

Types

ForeignFunction -- see foreignFunction -- construct a foreign function
SharedLibrary -- a shared library
ForeignType -- abstract foreign type
ForeignObject -- foreign object
Pointer -- pointer to memory address

Author

Doug Torrance <[email protected]>

Certification

Version 0.4 of this package was accepted for publication in volume 15 of Journal of Software for Algebra and Geometry on 2024-12-17, in the article ForeignFunctions package for Macaulay2 (DOI: 10.2140/jsag.2025.15.1). That version can be obtained from the journal.

Version

This documentation describes version 0.5 of ForeignFunctions.

Citation

If you have used this package in your research, please cite it as follows:

@misc{ForeignFunctionsSource,
  title = {{ForeignFunctions: foreign function interface. Version~0.5}},
  author = {Doug Torrance},
  howpublished = {A \emph{Macaulay2} package available at
    \url{https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/packages}}
}

@article{ForeignFunctionsArticle,
  title = {{ForeignFunctions package for \emph{Macaulay2}}},
  author = {Doug Torrance},
  journal = {Journal of Software for Algebra and Geometry},
  volume = {15},
  year = {2024},
}

Exports

Types
- ForeignArrayType -- foreign array type
- ForeignFunction -- see foreignFunction -- construct a foreign function
- char' -- see ForeignIntegerType -- foreign integer type
- ForeignIntegerType -- foreign integer type
- int -- see ForeignIntegerType -- foreign integer type
- int8 -- see ForeignIntegerType -- foreign integer type
- int16 -- see ForeignIntegerType -- foreign integer type
- int32 -- see ForeignIntegerType -- foreign integer type
- int64 -- see ForeignIntegerType -- foreign integer type
- long -- see ForeignIntegerType -- foreign integer type
- short -- see ForeignIntegerType -- foreign integer type
- uchar -- see ForeignIntegerType -- foreign integer type
- uint -- see ForeignIntegerType -- foreign integer type
- uint8 -- see ForeignIntegerType -- foreign integer type
- uint16 -- see ForeignIntegerType -- foreign integer type
- uint32 -- see ForeignIntegerType -- foreign integer type
- uint64 -- see ForeignIntegerType -- foreign integer type
- ulong -- see ForeignIntegerType -- foreign integer type
- ushort -- see ForeignIntegerType -- foreign integer type
- ForeignObject -- foreign object
- charstarstar -- see ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- voidstarstar -- see ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- ForeignPointerType -- foreign pointer type
- voidstar -- see ForeignPointerType -- foreign pointer type
- double -- see ForeignRealType -- foreign real type
- float -- see ForeignRealType -- foreign real type
- ForeignRealType -- foreign real type
- charstar -- see ForeignStringType -- foreign string type
- ForeignStringType -- foreign string type
- ForeignStructType -- foreign struct type
- ForeignType -- abstract foreign type
- ForeignUnionType -- foreign union type
- ForeignVoidType -- foreign void type
- void -- see ForeignVoidType -- foreign void type
- mpfrT -- MPFR multiple-precision floating-point type
- mpzT -- GMP arbitrary-precision integer type
- Pointer -- pointer to memory address
- SharedLibrary -- a shared library
Functions and commands
- address -- pointer to type or object
- foreignArrayType -- construct a foreign array type
- foreignFunction -- construct a foreign function
- foreignObject -- construct a foreign object
- foreignPointerArrayType -- construct a foreign pointer array type
- foreignStructType -- construct a foreign struct type
- foreignSymbol -- get a foreign symbol
- foreignUnionType -- construct a foreign union type
- getMemory -- allocate memory using the garbage collector
- openSharedLibrary -- open a shared library
Methods
- * Pointer = Thing -- see * voidstar = Thing -- assign value to object at address
- * voidstar = Thing -- assign value to object at address
- address(ForeignObject) -- see address -- pointer to type or object
- address(ForeignType) -- see address -- pointer to type or object
- address(Nothing) (missing documentation)
- expression(mpfrT) (missing documentation)
- foreignArrayType(ForeignType,ZZ) -- see foreignArrayType -- construct a foreign array type
- foreignArrayType(String,ForeignType,ZZ) -- see foreignArrayType -- construct a foreign array type
- ForeignType * ZZ -- see foreignArrayType -- construct a foreign array type
- ZZ * ForeignType -- see foreignArrayType -- construct a foreign array type
- ForeignArrayType VisibleList -- cast a Macaulay2 list to a foreign array
- foreignFunction(Pointer,String,ForeignType,VisibleList) -- see foreignFunction -- construct a foreign function
- foreignFunction(SharedLibrary,String,ForeignType,ForeignType) -- see foreignFunction -- construct a foreign function
- foreignFunction(SharedLibrary,String,ForeignType,VisibleList) -- see foreignFunction -- construct a foreign function
- foreignFunction(String,ForeignType,ForeignType) -- see foreignFunction -- construct a foreign function
- foreignFunction(String,ForeignType,VisibleList) -- see foreignFunction -- construct a foreign function
- ForeignIntegerType Number -- cast a Macaulay2 number to a foreign integer object
- new int8 from ZZ -- see ForeignIntegerType Number -- cast a Macaulay2 number to a foreign integer object
- new int16 from ZZ -- see ForeignIntegerType Number -- cast a Macaulay2 number to a foreign integer object
- new int32 from ZZ -- see ForeignIntegerType Number -- cast a Macaulay2 number to a foreign integer object
- new int64 from ZZ -- see ForeignIntegerType Number -- cast a Macaulay2 number to a foreign integer object
- new uint8 from ZZ -- see ForeignIntegerType Number -- cast a Macaulay2 number to a foreign integer object
- new uint16 from ZZ -- see ForeignIntegerType Number -- cast a Macaulay2 number to a foreign integer object
- new uint32 from ZZ -- see ForeignIntegerType Number -- cast a Macaulay2 number to a foreign integer object
- new uint64 from ZZ -- see ForeignIntegerType Number -- cast a Macaulay2 number to a foreign integer object
- foreignObject(ForeignObject) -- see foreignObject -- construct a foreign object
- foreignObject(Number) -- see foreignObject -- construct a foreign object
- foreignObject(Pointer) -- see foreignObject -- construct a foreign object
- foreignObject(String) -- see foreignObject -- construct a foreign object
- foreignObject(VisibleList) -- see foreignObject -- construct a foreign object
- foreignObject(ZZ) -- see foreignObject -- construct a foreign object
- charstarstar _ ZZ -- see ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- charstarstar _ ZZ = Thing -- see ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- iterator(charstarstar) -- see ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- iterator(voidstarstar) -- see ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- length(charstarstar) -- see ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- length(voidstarstar) -- see ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- voidstarstar _ ZZ -- see ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- voidstarstar _ ZZ = Thing -- see ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
- foreignPointerArrayType(ForeignType) -- see foreignPointerArrayType -- construct a foreign pointer array type
- foreignPointerArrayType(String,ForeignType) -- see foreignPointerArrayType -- construct a foreign pointer array type
- ForeignPointerArrayType VisibleList -- cast a Macaulay2 list to a foreign pointer array
- new charstarstar from VisibleList -- see ForeignPointerArrayType VisibleList -- cast a Macaulay2 list to a foreign pointer array
- new voidstarstar from VisibleList -- see ForeignPointerArrayType VisibleList -- cast a Macaulay2 list to a foreign pointer array
- ForeignPointerType Pointer -- cast a Macaulay2 pointer to a foreign pointer
- ForeignRealType Number -- cast a Macaulay2 number to a foreign real object
- ForeignRealType RRi -- see ForeignRealType Number -- cast a Macaulay2 number to a foreign real object
- new double from RR -- see ForeignRealType Number -- cast a Macaulay2 number to a foreign real object
- new float from RR -- see ForeignRealType Number -- cast a Macaulay2 number to a foreign real object
- ForeignStringType String -- cast a Macaulay2 string to a foreign string
- foreignStructType(String,Option) -- see foreignStructType -- construct a foreign struct type
- foreignStructType(String,VisibleList) -- see foreignStructType -- construct a foreign struct type
- ForeignStructType HashTable -- see ForeignStructType VisibleList -- cast a hash table to a foreign struct
- ForeignStructType VisibleList -- cast a hash table to a foreign struct
- foreignSymbol(SharedLibrary,String,ForeignType) -- see foreignSymbol -- get a foreign symbol
- foreignSymbol(String,ForeignType) -- see foreignSymbol -- get a foreign symbol
- net(ForeignType) -- see ForeignType -- abstract foreign type
- ForeignType * voidstar -- dereference a voidstar object
- ForeignStructType ForeignObject -- see ForeignType ForeignObject -- cast a foreign object to the given foreign type
- ForeignType ForeignObject -- cast a foreign object to the given foreign type
- ForeignType Pointer -- dereference a pointer
- foreignUnionType(String,Option) -- see foreignUnionType -- construct a foreign union type
- foreignUnionType(String,VisibleList) -- see foreignUnionType -- construct a foreign union type
- ForeignUnionType Thing -- cast a thing to a foreign union
- ForeignVoidType Nothing -- see ForeignVoidType -- foreign void type
- getMemory(ForeignType) -- see getMemory -- allocate memory using the garbage collector
- getMemory(ForeignVoidType) -- see getMemory -- allocate memory using the garbage collector
- getMemory(ZZ) -- see getMemory -- allocate memory using the garbage collector
- new mpfrT from RR -- see mpfrT -- MPFR multiple-precision floating-point type
- value(mpfrT) -- see mpfrT -- MPFR multiple-precision floating-point type
- new mpzT from ZZ -- see mpzT -- GMP arbitrary-precision integer type
- value(mpzT) -- see mpzT -- GMP arbitrary-precision integer type
- net(ForeignFunction) (missing documentation)
- new ForeignType (missing documentation)
- openSharedLibrary(String) -- see openSharedLibrary -- open a shared library
- Pointer + ZZ -- see Pointer -- pointer to memory address
- Pointer - ZZ -- see Pointer -- pointer to memory address
- ZZ + Pointer -- see Pointer -- pointer to memory address
- registerFinalizer(ForeignObject,Function) -- register a finalizer for a foreign object
- describe(SharedLibrary) -- see SharedLibrary -- a shared library
- expression(SharedLibrary) -- see SharedLibrary -- a shared library
- net(SharedLibrary) -- see SharedLibrary -- a shared library
- texMath(SharedLibrary) -- see SharedLibrary -- a shared library
- toExternalString(SharedLibrary) -- see SharedLibrary -- a shared library
- toString(SharedLibrary) -- see SharedLibrary -- a shared library
- size(ForeignType) -- size of a foreign type
- describe(ForeignObject) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- expression(double) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- expression(float) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- expression(ForeignObject) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- net(ForeignObject) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- texMath(ForeignObject) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- toExternalString(ForeignObject) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- toString(ForeignObject) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(charstar) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(charstarstar) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(double) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(float) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(int8) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(int16) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(int32) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(int64) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(uint8) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(uint16) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(uint32) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(uint64) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(voidstar) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
- value(voidstarstar) -- see value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
Symbols
- Variadic -- see foreignFunction -- construct a foreign function
- Atomic -- see getMemory -- allocate memory using the garbage collector
Other things
- nullPointer -- the null pointer

For the programmer

The object ForeignFunctions is a package, defined in ForeignFunctions.m2.

The source of this document is in ForeignFunctions.m2:752:0.