|Did you know ...
|Notes on Using Foreign Code
The functions in this section are primarily intended for debugging
foreign extensions or embedded Prolog. Violating the constraints of the
foreign interface often leads to crashes in a subsequent garbage
collection. If this happens, the system needs to be compiled for
cmake -DCMAKE_BUILD_TYPE=Debug, after which
all functions and predicates listed below are available to use from the
debugger (e.g. gdb) or can be placed at critical location in your
code or the system code.
user_error stream. Depth
is the number of frames to dump. Flags is a bitwise or of the
(gdb) printf "%s", PL_backtrace_string(25,0)
The source distribution provides the script
that exploits gdb and PL_backtrace_string()
to print stack traces in various formats for a SWI-Prolog process, given
its process id.
this is actually implemented in the current version and
FALSE otherwise. The actual implementation only exists if
the system is compiled with the cflag
-DO_MAINTENANCE. This is not the default.
TRUE this is actually implemented in the current
FALSE otherwise. The actual implementation only
exists if the system is compiled with the cflag
-DO_MAINTENANCE. This is not the default.
The Prolog kernel sources use the macro DEBUG(Topic, Code).
These macros are disabled in the production version and must be enabled
by recompiling the system as described above. Specific topics can be
enabled and disabled using the predicates prolog_debug/1
In addition, they can be activated from the commandline using
-d topics, where
topics is a comma-separated list of debug topics to enable.
For example, the code below adds many consistency checks and prints
messages if the Prolog signal handler dispatches signals.
$ swipl -d chk_secure,msg_signal
src/pl-debug.h. Please search the sources to find out what
is actually printed and when. We highlight one topic here:
These predicates require the system to be compiled for debugging
These functions require the system to be compiled for debugging using
SWI-Prolog's heap memory allocation is based on the malloc(3) library routines. SWI-Prolog provides the functions below as a wrapper around malloc(). Allocation errors in these functions trap SWI-Prolog's fatal-error handler, in which case PL_malloc() or PL_realloc() do not return.
Portable applications must use PL_free()
to release strings returned by PL_get_chars()
BUF_MALLOC argument. Portable applications may
use both PL_malloc()
and friends or malloc() and friends but should not mix these two
sets of functions on the same memory.
Great care is taken to ensure binary compatibility of foreign extensions between different Prolog versions. Only the much less frequently used stream interface has been responsible for binary incompatibilities.
Source code that relies on new
features of the foreign interface can use the macro
to find the version of
SWI-Prolog.h and PL_query()
using the option
PL_QUERY_VERSION to find the version of the attached Prolog
system. Both follow the same numbering schema explained with PL_query().
As of SWI-Prolog 8.3.2 the foreign API provides access to the
internal thread-safe and lock-free hash tables that associate pointers
or objects that fit in a pointer such as atoms (
argument against providing these functions is that they have little to
do with Prolog. The argument in favor is that it is hard to implement
efficient lock-free tables without low-level access to the underlying
Prolog threads and exporting this interface has a low cost.
The functions below can only be called if the calling thread is associated with a Prolog thread. Failure to do so causes the call to be ignored or return the failure code where applicable.
NULL if key
does not appear in the table.
this function returns the existing value without updating the table. If
PL_HT_UPDATE the old value is replaced
and the function returns the old value. If
message and backtrace are printed and the function returns NULL
if key is already in the table.
This section is only relevant for Unix users on platforms supported by valgrind. Valgrind is an excellent binary instrumentation platform. Unlike many other instrumentation platforms, valgrind can deal with code loaded through dlopen().
The callgrind tool can be used to profile foreign code loaded
under SWI-Prolog. Compile the foreign library adding -g
option to gcc or swipl-ld. By setting the environment
yes, SWI-Prolog will not
release loaded shared objects using dlclose(). This trick is
required to get source information on the loaded library. Without,
valgrind claims that the shared object has no debugging information.236Tested
using valgrind version 3.2.3 on x64. Here is the complete
sequence using bash as login shell:
% VALGRIND=yes valgrind --tool=callgrind pl <args> <prolog interaction> % kcachegrind callgrind.out.<pid>
Instead of valgrind, you can use AddressSanitizer. Here is a short example for building with asan enabled and then running the resulting binary. When you exit swipl, a message is printed and any leaks are printed. During execution, other messages may be printed out, such as freeing an address twice or using freed or unallocated memory.
% cd build.sanitize % cmake -G Ninja -DCMAKE_BUILD_TYPE=Sanitize .. % ninja % ASAN_OPTIONS=detect_leaks=1 build.sanitize/src/swipl <prolog interaction> % halt Running LSAN memory leak check (reclaim_memory=1) No leaks detected
In the current version of the system all public C functions of SWI-Prolog are in the symbol table. This can lead to name clashes with foreign code. Someday I should write a program to strip all these symbols from the symbol table (why does Unix not have that?). For now I can only suggest you give your function another name. You can do this using the C preprocessor. If---for example---your foreign package uses a function warning(), which happens to exist in SWI-Prolog as well, the following macro should fix the problem:
#define warning warning_
Note that shared libraries do not have this problem as the shared library loader will only look for symbols in the main executable for symbols that are not defined in the library itself.
The term reference mechanism was first used by Quintus Prolog version 3.
SICStus Prolog version 3 is strongly based on the Quintus interface. The
described SWI-Prolog interface is similar to using the Quintus or
SICStus interfaces, defining all foreign-predicate arguments of type
+term. SWI-Prolog explicitly uses type
while Quintus and SICStus use <name> and <arity>.
As the names of the functions differ from Prolog to Prolog, a simple
macro layer dealing with the names can also deal with this detail. For
#define QP_put_functor(t, n, a) \ PL_put_functor(t, PL_new_functor(n, a))
PL_unify_*() functions are lacking from the Quintus
and SICStus interface. They can easily be emulated, or the put/unify
approach should be used to write compatible code.
The PL_open_foreign_frame()/PL_close_foreign_frame() combination is lacking from both other Prologs. SICStus has PL_new_term_refs(0), followed by PL_reset_term_refs(), that allows for discarding term references.
The Prolog interface for the graphical user interface package XPCE shares about 90% of the code using a simple macro layer to deal with different naming and calling conventions of the interfaces.