Did you know ... Search Documentation:
qpforeign.pl -- Quintus compatible foreign loader
PublicShow source

This module defines a Quintus compatible foreign language interface based on the foreign_file/2 and foreign/3 declarations.

Predicates:

load_foreign_files
Load all foreign files defined with foreign_file/2 statement in the current module.
load_foreign_files(+Files, +Libs)
Load specified foreign files, linking them with the given libraries
load_foreign_files(+SharedObject, +Files, +Libs)
As load_foreign_files/2, but first tries to load `SharedObject'. If the SharedObject exists it is loaded using load_foreign_library/1. Otherwise it is first created with make_shared_object/3.
make_shared_object(+SharedObject, +Files, +Libs)
Generate a wrapper and link it using plld to the given SharedObject.
make_foreign_wrapper_file(+Files, +OutBase)
Generate wrapper for the named object files in OutBase.c.
make_foreign_wrapper_file(+Files)
Generate wrapper for all declared object files in OutBase.c.

Example:

foreign_file('-lm', [sin/2]).
foreign(sin, c, sin(+float, [-float])).
:- load_foreign_files,
   abolish(foreign_file, 2),
   abolish(foreign, 3).

Supported types:

SpecPrologC
integerintegerlong
floatfloat,integerdouble
singlefloat,integersingle
stringatom,stringchar *
atomatomatom identifier (type atomic)

NOTE This modules requires a correctly functioning swipl-ld and load_foreign_library/1 on your system. If this isn't the case use make_foreign_wrapper_file/[1,2] to generate a wrapper and use static embedding.

bug
- Only supports C-interface
- Insufficient checking for misusage.
- Documentation is too short and very outdated
Source make_wrappers(+PrologHeads, +Module, +OutStream)[private]
Source make_wrapper(+Stream, :PrologHead)[private]
Generates a C-wrapper function for the given foreign defined Prolog predicate. The wrapper is called _plw_<predname><arity>.
Source get_foreign_head(:Spec, -Func, -Head)[private]
Get 3rd argument of relevant foreign/3 clause. Seems there are two versions. In Quintus Spec was a predicate specification and in SICStus it seems to be a (C) function name.
Source cvt_name(+Type, +IO, -Suffix) is det[private]
Source make_C_header(+Stream, +WrapperName, +Arity)[private]
Write function-header for the wrapper. This is easy as the the return-type is always foreign_t and the arguments are always of type `term_t'. The arguments are simply named `a', `b', ...
Source make_C_decls(+Stream, :PrologHead)[private]
Writes the C variable declarations. If the return value is used a variable named `rval' is created. For each input parameter a C variable named i<argname> is created; for each output variable o<argname>.
Source make_C_prototype(+Stream, :PrologHead)[private]
If the function handles floats or doubles, make a prototype declaration for it to avoid unwanted conversions.
Source make_C_input_conversions(+Stream, :PrologHead)[private]
Generate the input checking and conversion code. Assumes boolean functions that take a Prolog term_t as first argument and a pointer to the requested C-type as a second argument. Function returns 0 if the conversion fails.
Source make_C_call(+Stream, :PrologHead, +CFunction)[private]
Generate the actual call to the foreign function. Input variables may be handed directly; output variables as a pointer to the o<var>, except for output-variables of type term.
Source make_C_wrapper_setup(+Stream)[private]
Call SP_WRAP_INIT() when running on SICStus. This supports SP_fail() and SP_raise_exception().
Source make_C_wrapper_check(+Stream)[private]
Call SP_WRAP_CHECK_STATE() when running on SICStus. This supports SP_fail() and SP_raise_exception().
Source make_C_output_conversions(+Stream, :PrologHead)[private]
Generate conversions for the output arguments and unify them with the Prolog term_t arguments.
Source make_C_init(+Stream, +InstallFunc, +InitFunc, +Module, +PredList)[private]
Generate an array of PL_extension structures, that may be used to create a statically linked image as well as through the PL_load_extensions() call.

Of the supported PL_FA_<FLAGS>, TRANSPARENT may be declared by looking at the transparent (meta_predivate) attribute of the predicate.

Source make_C_deinit(+Stream, +UninstallFunc, +DeInitFunc) is det[private]
Write the uninstall function
Source make_C_file_header(+Stream)[private]
Output the generic header declarations needed and some comments
Source load_foreign_files is det
Source load_foreign_files(:Files, +Libs) is det
Source load_foreign_files(+SharedObject, :Files, +Libs) is det
Calls make_foreign_wrapper_file(+File), compiles the wrapper and loads the predicates.
Source make_shared_object(+Object, :Files, +Libs) is det
Generate a wrapper and link it using plld to the given SharedObject.
Source make_foreign_wrapper_file(:OutFile) is det
Source make_foreign_wrapper_file(:Files, +OutFile) is det
Just output the wrapper file to the named .c file. May be used to prepare for static linking or the preparation of the native SWI-Prolog foreign-file.
Source make_foreign_resource_wrapper(:Resource, +ResBase, +FileBase)
Create a wrapper-file for the given foreign resource
Source load_foreign_resource(:Resource, +Dir)
Load a foreign module. First try to load from the same direcory as the Prolog file. Otherwise load using SWI-Prolog's default search path.
Source map_C_type(+Prolog, -C)[private]
Map Prolog interface type declarations into C types.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

Source load_foreign_files(Arg1, Arg2)
Source make_foreign_wrapper_file(Arg1, Arg2)
Source load_foreign_files(Arg1, Arg2, Arg3)