13 KiB

Raw Blame History

Portable Foreign Function Interface for R7RS schemes

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

Any help in form of constructive advice and bug reports are appreciated.

Issue trackers

Maling lists

Jenkins.

Goals
Non Goals
Status
Implementation status
Implementation table
Other Implementations
Documentation
- Usage notes
- Reference

Goals

Support only R7RS implementations
Same interface on all implementations
- Some things that are procedures on one implementation are macros on other, but they must behave the same
Stability and being boring after 1.0.0 is reached

Non goals

To have every possible FFI feature
Compiling of used library C code at any point
- That is no stubs, no C code generated by the library and so on
- The pffi library itself may require compilation on installation

Status

Currently the interface of the library is in okay shape. It propably will not change much but no guarantees are being made just yet.

Due to supporting many different Scheme implementations, different parts of this software are in different stage. As a whole it is still in alpha stage. That said the interface should not be changing anymore and support for some implementations are in beta.

Implementation status

Alpha

Anything not in beta or done, not recommended to use.

Beta

Usage can be started but might still be quite buggy.

Guile
Sagittarius
Racket

Done

Usage recommended.

None yet

Implementation table

	Chibi	Chicken 5	Cyclone	Gambit	Gauche	Gerbil	Guile	Kawa	Larceny	Mosh	Racket	Sagittarius	Skint	STklos	tr7	Ypsilon
pffi-init	X	X	X	X	X	X	X	X	X	X	X	X	X	X
pffi-size-of	X	X	X	X			X	X		X	X	X		X
pffi-shared-object-auto-load	X	X	X				X	X		X	X	X		X
pffi-shared-object-load	X	X	X				X	X		X	X	X		X
pffi-pointer-null	X	X	X				X	X		X	X	X		X
pffi-pointer-null?	X	X	X				X	X		X	X	X		X
pffi-pointer-allocate	X	X	X				X	X		X	X	X		X
pffi-pointer?	X	X	X				X	X		X	X	X		X
pffi-pointer-free	X	X	X				X	X		X	X	X		X
pffi-pointer-set!	X	X	X				X	X		X	X	X
pffi-pointer-get	X	X	X				X	X		X	X	X
pffi-string->pointer	X	X	X				X	X		X	X	X
pffi-pointer->string	X	X	X				X	X		X	X	X
pffi-struct-make	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X
pffi-struct-size	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X
pffi-struct-pointer	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X
pffi-struct-offset-get	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X
pffi-struct-get	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X
pffi-struct-set!	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X	X
pffi-define	X	X	X				X	X		X	X	X
pffi-define-callback		X					X			X	X	X

Other implementations

LIPS
- Will work on nodejs by using some C FFI library from npm
- Javascript side needs design
Biwascheme
- Will work on nodejs by using some C FFI library from npm
- Javascript side needs design
MIT-Scheme
s7
Airship
Other gambit targets
- Gambit compiles to different targets other than C too, for example Javascript. It would be cool and interesting to see if this FFI could also support some of those
- When LIPS and Biwascheme Javascript side is done then Gambit should be done too
s48-r7rs
prescheme
Loko
- Desires no C interop, I can respect that

Documentation

Usage notes

Chibi
- Install libffi-dev
- Build with:
  - chibi-ffi retropikzel/r7rs-pffi/r7rs-pffi-chibi.stub
  - ${CC} -o retropikzel/r7rs-pffi/r7rs-pffi-chibi.so -fPIC -shared retropikzel/r7rs-pffi/r7rs-pffi-chibi.c -lchibi-scheme -lffi
Chicken 5
- Needs r7rs egg
Kawa
- Needs at least Java version 22
- Needs jvm flags:
  - --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
Racket
- Needs racket-r7rs

Reference

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
pointer

Procedures and macros

Some of these are procedures and some macros, it might also change implementation to implementation.

pffi-init

Always call this first, on most implementation it does nothing but some implementations might need initialisation run.

pffi-size-of type -> number

Returns the size of the type.

pffi-align-of type -> number

Returns the align of the type.

pffi-shared-object-auto-load

TODO

pffi-shared-object-load headers path

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

Headers is a list of strings needed to be included, for example

(list "curl/curl.h")

Path is the full path of the shared object without any "lib" prefix or ".so/.dll" suffix. For example:

"curl"

pffi-pointer-null -> pointer

Returns a new NULL pointer.

pffi-pointer-null? pointer -> boolean

Returns #t if given pointer is null pointer, #f otherwise.

pffi-pointer-allocate size -> pointer

Returns newly allocated pointer of given size.

pffi-pointer? object -> boolean

Returns #t if given object is pointer, #f otherwise.

pffi-pointer-free pointer

Frees given pointer.

pffi-pointer-set! pointer type offset value

Sets the value on a pointer on given offset. For example:

(define p (pffi-pointer-allocate 128))
(pffi-pointer-set! p 'int 64 100)

Would set the offset of 64, on pointer p to value 100.

pffi-pointer-get pointer type offset -> object

Gets the value from a pointer on given offset. For example:

(define p (pffi-pointer-allocate 128))
(pffi-pointer-set! p 'int 64 100)
(pffi-pointer-get p 'int 64)
> 100

pffi-string->pointer string -> pointer

Makes pointer out of a given string.

pffi-pointer->string pointer -> string

Makes string out of a given pointer.

pffi-struct-make name members . pointer -> pffi-struct

Creates a new pffi-struct and allocates pointer for it. The members argument is a list of member names and types. For example:

(define s (pffi-struct-make 'test '((int . r) (int . g) (int . b))))

pffi-struct-size pffi-struct -> number

Returns the size of a given pffi-struct. For example:

(define s (pffi-struct-make 'test '((int . r) (int . g) (int . b))))
(pffi-struct-size s)
> 12

pffi-struct-pointer pffi-struct -> pointer

Returns the pointer that holds the struct content. You need to use this when passing a struct as a pointer to foreign functions.

(define s (pffi-struct-make 'test '((int . r) (int . g) (int . b))))
(pffi-struct-pointer s)

pffi-struct-offset-get member-name -> number

Returns the offset of a struct member with given name.

pffi-struct-get pffi-struct member-name -> object

Returns the value of the givens struct member.

pffi-struct-set! pffi-struct member-name value

Sets the value of the givens struct member. It is up to you to make sure that the type of value is correct.

pffi-define scheme-name shared-object c-name return-type argument-types

Defines a new foreign function to be used from Scheme code. For example:

(define libc-stdlib
    (cond-expand
        (windows (pffi-shared-object-auto-load (list "stdlib.h") (list) "ucrtbase" (list "")))
        (else (pffi-shared-object-auto-load (list "stdlib.h") (list) "c" (list "" ".6")))))
(pffi-define c-puts libc-stdlib 'puts 'int (list 'pointer))
(c-puts "Message brought to you by FFI!")

pffi-define-callback scheme-name return-type argument-types procedure

Defines a new Sceme function to be used as callback to C code. For example:

; Load the shared library
(define libc-stdlib
    (cond-expand
        (windows (pffi-shared-object-auto-load (list "stdlib.h") (list) "ucrtbase" (list "")))
        (else (pffi-shared-object-auto-load (list "stdlib.h") (list) "c" (list "" ".6")))))

; Define C function that takes a callback
(pffi-define qsort libc-stdlib 'qsort 'void (list 'pointer 'int 'int 'callback))

; Define our callback
(pffi-define-callback compare
                      'int
                      (list 'pointer 'pointer)
                      (lambda (pointer-a pointer-b)
                        (let ((a (pffi-pointer-get pointer-a 'int 0))
                              (b (pffi-pointer-get pointer-b 'int 0)))
                          (cond ((> a b) 1)
                                ((= a b) 0)
                                ((< a b) -1)))))

; Create new array of ints to be sorted
(define array (pffi-pointer-allocate (* (pffi-size-of 'int) 3)))
(pffi-pointer-set! array 'int (* (pffi-size-of 'int) 0) 3)
(pffi-pointer-set! array 'int (* (pffi-size-of 'int) 1) 2)
(pffi-pointer-set! array 'int (* (pffi-size-of 'int) 2) 1)

(display array)
(newline)
;> (3 2 1)

; Sort the array
(qsort array 3 (pffi-size-of 'int) compare)

(display array)
(newline)
;> (1 2 3)

13 KiB Raw Blame History