105 lines
3.6 KiB
Prolog
105 lines
3.6 KiB
Prolog
:- module(ffi, [use_foreign_module/2, foreign_struct/2]).
|
|
|
|
/** Foreign Function Interface
|
|
|
|
This module contains predicates used to call native code (exposed by the C ABI).
|
|
It uses [libffi](https://sourceware.org/libffi/) under the hood. The bridge is very simple
|
|
and is very unsafe and should be used with care. FFI isn't the only way to communicate with
|
|
the outside world in Prolog: sockets, pipes and HTTP may be good enough for your use case.
|
|
|
|
The main predicate is `use_foreign_module/2`. It takes a library name (which depending on the
|
|
operating system could be a `.so`, `.dylib` or `.dll` file). and a list of functions. Each
|
|
function is defined by its name, a list of the type of the arguments, and the return argument.
|
|
|
|
Types available are: `sint8`, `uint8`, `sint16`, `uint16`, `sint32`, `uint32`, `sint64`,
|
|
`uint64`, `f32`, `f64`, `cstr`, `void`, `bool`, `ptr` and custom structs, which can be defined
|
|
with `foreign_struct/2`.
|
|
|
|
After that, each function on the lists maps to a predicate created in the ffi module which
|
|
are used to call the native code.
|
|
The predicate takes the functor name after the function name. Then, the arguments are the input
|
|
arguments followed by a return argument. However, functions with return type `void` or `bool`
|
|
don't have that return argument. Predicates with `void` always succeed and `bool` predicates depend
|
|
on the return value on the native side.
|
|
|
|
```
|
|
ffi:FUNCTION_NAME(+InputArg1, ..., +InputArgN, -ReturnArg). % for all return types except void and bool
|
|
ffi:FUNCTION_NAME(+InputArg1, ..., +InputArgN). % for void and bool
|
|
```
|
|
|
|
## Example
|
|
|
|
For example, let's see how to define a function from the [raylib](https://www.raylib.com/) library.
|
|
|
|
```
|
|
?- use_foreign_module("./libraylib.so", ['InitWindow'([sint32, sint32, cstr], void)]).
|
|
```
|
|
|
|
This creates a `'InitWindow'` predicate under the ffi module. Now, we can call it:
|
|
|
|
```
|
|
?- ffi:'InitWindow'(800, 600, "Scryer Prolog + Raylib").
|
|
```
|
|
|
|
And a new window should pop up!
|
|
*/
|
|
|
|
:- use_module(library(lists)).
|
|
:- use_module(library(error)).
|
|
|
|
%% foreign_struct(+Name, +Elements).
|
|
%
|
|
% Defines a new struct type with name Name, composed of the elements Elements, which is a list
|
|
% of other types.
|
|
%
|
|
% The name of the types doesn't matter, but the order of Elements must match the ones in the
|
|
% native code.
|
|
%
|
|
% Example:
|
|
%
|
|
% ```
|
|
% ?- foreign_struct(color, [uint8, uint8, uint8, uint8]).
|
|
% ```
|
|
foreign_struct(Name, Elements) :-
|
|
'$define_foreign_struct'(Name, Elements).
|
|
|
|
use_foreign_module(LibName, Predicates) :-
|
|
'$load_foreign_lib'(LibName, Predicates),
|
|
maplist(assert_predicate, Predicates).
|
|
|
|
assert_predicate(PredicateDefinition) :-
|
|
PredicateDefinition =.. [Name, Inputs, void],
|
|
length(Inputs, NumInputs),
|
|
functor(Head, Name, NumInputs),
|
|
term_variables(Head, TermList),
|
|
Body = (
|
|
'$foreign_call'(Name, TermList, _),!
|
|
),
|
|
Predicate = (Head:-Body),
|
|
assertz(ffi:Predicate).
|
|
|
|
assert_predicate(PredicateDefinition) :-
|
|
PredicateDefinition =.. [Name, Inputs, bool],
|
|
length(Inputs, NumInputs),
|
|
functor(Head, Name, NumInputs),
|
|
term_variables(Head, TermList),
|
|
Body = (
|
|
'$foreign_call'(Name, TermList, 1),!
|
|
),
|
|
Predicate = (Head:-Body),
|
|
assertz(ffi:Predicate).
|
|
|
|
assert_predicate(PredicateDefinition) :-
|
|
PredicateDefinition =.. [Name, Inputs, Return],
|
|
\+ member(Return, [void, bool]),
|
|
length(Inputs, NumInputs),
|
|
NumArgs is NumInputs + 1,
|
|
functor(Head, Name, NumArgs),
|
|
term_variables(Head, TermList),
|
|
Body = (
|
|
lists:append(TermListInputs, [TermListReturn], TermList),
|
|
'$foreign_call'(Name, TermListInputs, TermListReturn),!
|
|
),
|
|
Predicate = (Head:-Body),
|
|
assertz(ffi:Predicate).
|