Portable Foreign Function Interface for R7RS schemes

Foreign function interface that is supported on multiple R7RS Sceheme implementations.

Note that this software is in alpha stage.

Any help in form of constructive advice, bug reports, feature suggestions are appreciated.

Got a bug?

Got a feature suggestion?

Got a question?

Goals

• Support only R7RS implementations
  • Needs to have cond-expand and library support atleast (propably much more)
• Same interface on all implementations
  • Some things that are procedures on one implementation are macros on other, but they must behave the same

Non goals

• To support all R7RS implementations
• To have every possible FFI feature
• Compiling of C code at any point
  • That is no stubs, no C code generated by the library and so on

All tests (there is not that many yet) pass

• Sagittarius
• Guile
• Kawa
  • Needs atleast java 21
  • Needs jvm flags
    • java --add-exports java.base/jdk.internal.foreign.abi=ALL-UNNAMED --add-exports java.base/jdk.internal.foreign.layout=ALL-UNNAMED --add-exports java.base/jdk.internal.foreign=ALL-UNNAMED --enable-native-access=ALL-UNNAMED --enable-preview -jar kawa.jar FILENAME.scm
• Racket
• Chicken

Not all tests pass

• Gambit

Support waiting for the implementation

• LIPS
  • Waiting for implementation to have cond-expand and library support
  • Will only work on nodejs
• Biwascheme
  • Waiting for implementation to have cond-expand and library support
  • Will only work on nodejs

Support needs to be investigated

• Gerbil
• Ypsilon
• Larceny

Support maybe possible/dreaming about

• Airship

Not supported

• STKlos
  • No callbacks in FFI
• Cyclone
  • No callbacks in FFI
• Chibi
  • FFI requires C code
• MIT-Scheme
  • FFI requires C code
• tr7
  • FFI requires C code
• Gauche
  • FFI requires C code
• Loko
  • Desires no C interop, I can respect that

Hacking

• You will need to have scheme_testrunner installed to run tests on large scale
  • You can also run them on your machine

Pull requests

Pull requests for bug fixes, additional implementation support and additional tests are appreciated. But please do not change the interface (library exports) and if you add support for implementation then all exported procedures of main.sld need to be implemented and tests must pass.

Documentation

On some implementations these are procedures, on some macros.

The arguments are in form

• NAME - TYPE

The return value is in form

• TYPE

Types

Types are given as symbols, for example 'int8 or 'pointer.

• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64
• uint64
• char
• unsigned-char
• short
• unsigned-short
• int
• unsigned-int
• long
• unsigned-long
• float
• double
• string
• pointer

Procedures or macros

pffi-shared-object-auto-load

Arguments:

• headers - (list string ...)
  • C headers of the library
  • For example (list "curl/curl.h")
• object-name - symbol
  • The name of the dynamic library file you want to load
  • Without the "lib" in front of it
  • Without the ".so" or ".dll" at the end
• additional-versions - (list string...)
  • For example (list ".0" ".1")
• additional-paths - (list string...)
  • Any additional paths you want to search for the library
  • For example (list "./mylibs")

Returns:

• object
  • Shared object, the type depends on the implementation

pffi-shared-object-load

It is recommended to use the pffi-shared-object-auto-load instead of this directly.

Arguments:

• headers - (list string ...)
  • Headers that need to be included
  • Example (list "curl/curl.h")
• path - string
  • The full path to the shared object you want to load, including any "lib" infront and .so/.dll at the end
  • Example "libcurl.so"

Returns:

• object
  • Shared object, the type depends on the implementation

pffi-define

Defines new foreign procedure.

Arguments:

• scheme-name
  • The name of the procedure used on scheme side
• shared-object - object
  • The shared object
  • Use pffi-shared-object-auto-load or pffi-shared-object-load to get this
• c-name - symbol
  • The name of the C function
• return-type - symbol
  • The return type of the C function
• arguments-types - (list symbol ...)
  • The C function argument types

pffi-define-callback

Defines new callback function.

Arguments:

• scheme-name
  • The name of the function used on scheme side
• return-type - symbol
  • The return type of the callback
• arguments-types - (list symbol ...)
  • The callback function argument types
• procedure - procedure
  • Procedure used as callback function
  • Argument count must mathc the argument-types count

pffi-size-of

Get the size of type.

Arguments:

• type - symbol
  • The type you want the size of

Returns:

• number
  • The size of the given type

pffi-pointer-allocate

Allocates a pointer of given size.

Arguments:

• size - number
  • The size of the pointer you want to allocate

Returns:

• object
  • A pointer of given size

pffi-pointer-null

Create a null pointer.

Returns:

• object
  • Null pointer

pffi-string->pointer

Arguments:

• string-content - string
  • The string you want to transform into pointer

Returns:

• object
  • Pointer of the given string

pffi-pointer->string

Arguments:

• pointer - object
  • The pointer you want to transform to string

Returns:

• string
  • String from the given pointer

pffi-pointer-free

Arguments:

• pointer - object
  • The pointer you want to free

pffi-pointer?

Arguments:

• object - object
  • The object you want to check wether it is a pointer or not

Returns:

• boolean
  • Returns true if given object is pointer, otherwise false

pffi-pointer-set!

Arguments:

• pointer - object
  • The pointer you want to modify
• type - symbol
  • The type of value that will be put into the pointer
• offset -number
  • The location of the value inside the pointer
  • For example: (+ (pffi-size-of 'int) (pffi-size-of 'pointer)) or 0
• value - object
  • The value to be placed into the object

pffi-pointer-get

Arguments:

• pointer - object
  • The pointer you want to get the value from
• type - symbol
  • The type of value you want to get
  • For example: 'int
• offset - number
  • The location of the value inside the pointer
  • For example: (+ (pffi-size-of 'int) (pffi-size-of 'pointer)) or 0

Returns:

• object
  • The value in the poiner in the given offset as given type

pffi-pointer-deref

Arguments:

• pointer
  • The pointer to dereference

Returns:

• object
  • Whatever the pointer holds