\chapter{Foreign Language Interface} \label{sec:foreign} \newlength{\tableft} \settowidth{\tableft}{\const{PL_QUERY_ORGSYMBOLFILE}} SWI-Prolog offers a powerful interface to C \cite{Kernighan:78}. The main design objectives of the foreign language interface are flexibility and performance. A foreign predicate is a C function that has the same number of arguments as the predicate represented. C functions are provided to analyse the passed terms, convert them to basic C types as well as to instantiate arguments using unification. Non-deterministic foreign predicates are supported, providing the foreign function with a handle to control backtracking. C can call Prolog predicates, providing both a query interface and an interface to extract multiple solutions from a non-deterministic Prolog predicate. There is no limit to the nesting of Prolog calling C, calling Prolog, etc. It is also possible to write the `main' in C and use Prolog as an embedded logical engine. \section{Overview of the Interface} \label{sec:foreignoverview} A special include file called \file{SWI-Prolog.h} should be included with each C source file that is to be loaded via the foreign interface. The installation process installs this file in the directory \file{include} in the SWI-Prolog home directory (\exam{?- current_prolog_flag(home, Home).}). This C header file defines various data types, macros and functions that can be used to communicate with SWI-Prolog. Functions and macros can be divided into the following categories: \begin{shortlist} \item Analysing Prolog terms \item Constructing new terms \item Unifying terms \item Returning control information to Prolog \item Registering foreign predicates with Prolog \item Calling Prolog from C \item Recorded database interactions \item Global actions on Prolog (halt, break, abort, etc.) \end{shortlist} \section{Linking Foreign Modules} \label{sec:foreignlink} Foreign modules may be linked to Prolog in two ways. Using \jargon{static linking}, the extensions, a (short) file defining main() which attaches the extension calls to Prolog, and the SWI-Prolog kernel distributed as a C library, are linked together to form a new executable. Using \jargon{dynamic linking}, the extensions are linked to a shared library (\fileext{so} file on most Unix systems) or dynamic link library (\fileext{DLL} file on Microsoft platforms) and loaded into the running Prolog process.% \footnote{The system also contains code to load \fileext{o} files directly for some operating systems, notably Unix systems using the BSD \file{a.out} executable format. As the number of Unix platforms supporting this quickly gets smaller and this interface is difficult to port and slow, it is no longer described in this manual. The best alternative would be to use the \idx{dld} package on machines that do not have shared libraries.} \subsection{What linking is provided?} \label{sec:foreign-linking} The \jargon{static linking} schema can be used on all versions of SWI-Prolog. Whether or not dynamic linking is supported can be deduced from the Prolog flag \prologflag{open_shared_object} (see \index{current_prolog_flag/2}\predref{current_prolog_flag}{2}). If this Prolog flag yields \const{true}, \index{open_shared_object/2}\predref{open_shared_object}{2} and related predicates are defined. See \secref{shlib} for a suitable high-level interface to these predicates. \subsection{What kind of loading should I be using?} \label{sec:foreign-linking-options} All described approaches have their advantages and disadvantages. Static linking is portable and allows for debugging on all platforms. It is relatively cumbersome and the libraries you need to pass to the linker may vary from system to system, though the utility program \program{swipl-ld} described in \secref{plld} often hides these problems from the user. Loading shared objects (DLL files on Windows) provides sharing and protection and is generally the best choice. If a saved state is created using \index{qsave_program/[1,2]}\predref{qsave_program}{[1,2]}, an \index{initialization/1}\predref{initialization}{1} directive may be used to load the appropriate library at startup. Note that the definition of the foreign predicates is the same, regardless of the linking type used. \InputIfFileExists{lib/shlib}{}{} \subsection{Low-level operations on shared libraries} \label{sec:sharedobj} The interface defined in this section allows the user to load shared libraries (\fileext{so} files on most Unix systems, \fileext{dll} files on Windows). This interface is portable to Windows as well as to Unix machines providing \manref{dlopen}{2} (Solaris, Linux, FreeBSD, Irix and many more) or \manref{shl_open}{2} (HP/UX). It is advised to use the predicates from \secref{shlib} in your application. \begin{description} \predicate{open_shared_object}{2}{+File, -Handle} \arg{File} is the name of a \jargon{shared object} file (DLL in MS-Windows). This file is attached to the current process, and \arg{Handle} is unified with a handle to the library. Equivalent to \exam{open_shared_object(File, Handle, [])}. See also \index{open_shared_object/3}\predref{open_shared_object}{3}, \index{load_foreign_library/1}\predref{load_foreign_library}{1} and \index{use_foreign_library/1}\predref{use_foreign_library}{1}. On errors, an exception \term{shared_object}{Action, Message} is raised. \arg{Message} is the return value from dlerror(). \predicate{open_shared_object}{3}{+File, -Handle, +Options} As \index{open_shared_object/2}\predref{open_shared_object}{2}, but allows for additional flags to be passed. Defined options are below. These options map to \const{RTLD_NOW}, \const{RTLD_LAZY}, \const{RTLD_GLOBAL}, \const{RTLD_NODELETE}, \const{RTLD_NOLOAD} and \const{RTLD_DEEPBIND} on systems where this predicate is implemented using dlopen() and these flags are supported. If the flag is not supported on the target OS, the corresponding option is silently ignored. \begin{description} \termitem{resolve}{Atom} When to resolve symbols. Values are \const{lazy} (default) or \const{now}. \termitem{visibility}{Atom} Visibility of the new symbols. Values are are \const{local} (default) or \const{global}, making the new symbols available to all subsequently loaded shared objects. \termitem{now}{Bool} \term{now}{true} is the same as \term{resolve}{now}. Provided for backward compatibility. \termitem{global}{Bool} \term{global}{true} is the same as \term{visibility}{global}. Provided for backward compatibility. \termitem{delete}{Bool} If \const{false}, include \const{RTLD_NODELETE}. \termitem{load}{Bool} if \const{false}, include \const{RTLD_NOLOAD}. This returns a handle to the object if it is already loaded and \const{NULL} otherwise. It causes this predicate to \jargon{fail silently} if the object is not loaded. \termitem{deepbind}{Bool} if \const{true}, include \const{RTLD_DEEPBIND}. \end{description} Note that these flags may not be supported by your operating system. Check the documentation of dlopen() or equivalent on your operating system. Unsupported flags are silently ignored. \predicate{close_shared_object}{1}{+Handle} Detach the shared object identified by \arg{Handle}. \predicate{call_shared_object_function}{2}{+Handle, +Function} Call the named function in the loaded shared library. The function is called without arguments and the return value is ignored. Normally this function installs foreign language predicates using calls to \cfuncref{PL_register_foreign}{}. \end{description} \subsection{Static Linking} \label{sec:static-linking} Older versions of SWI-Prolog were shipped by default with a \jargon{static library}. In recent versions we no longer ship a static library because practically every OS properly supports dynamic linking without serious drawbacks and dynamic linking has several advantages. It is on many platforms required to be able to load SWI-Prolog foreign libraries (see \index{use_foreign_library/1}\predref{use_foreign_library}{1}). Only on ELF based systems such as Linux we can load foreign libraries \emph{if} the main executable is linked to export its global symbols (\program{gcc} \exam{-rdynamic} option). Another advantage of dynamic libraries is that the user does not have to worry about libraries that this particular build of SWI-Prolog requires such as \file{libgmp} as well as OS specific libraries. If one really wants a static library, use the \program{CMake} flag \exam{-DSWIPL_STATIC_LIB=ON} while configuring a build from source. This causes building and installing \file{libswipl_static.a}. Note the \const{_static} postfix to avoid a name conflict on Windows between the \jargon{import library} and the \jargon{static library}.\footnote{As is, the Windows build is cross-compiled using MinGW which produces \file{libswipl_static.a}. This file can, as far as we know, \emph{not} be used by MSVC.}. \section{Interface Data Types} \label{sec:foreigntypes} \subsection{Type \ctype{term_t}: a reference to a Prolog term} \label{sec:type-term-t} The principal data type is \ctype{term_t}. Type \ctype{term_t} is what Quintus calls \ctype{QP_term_ref}. This name indicates better what the type represents: it is a \jargon{handle} for a term rather than the term itself. Terms can only be represented and manipulated using this type, as this is the only safe way to ensure the Prolog kernel is aware of all terms referenced by foreign code and thus allows the kernel to perform garbage collection and/or stack-shifts while foreign code is active, for example during a callback from C. A term reference is a C \ctype{uintptr_t}, representing the offset of a variable on the Prolog environment stack. A foreign function is passed term references for the predicate arguments, one for each argument. If references for intermediate results are needed, such references may be created using \cfuncref{PL_new_term_ref}{} or \cfuncref{PL_new_term_refs}{}. These references normally live till the foreign function returns control back to Prolog. Their scope can be explicitly limited using \cfuncref{PL_open_foreign_frame}{} and \cfuncref{PL_close_foreign_frame}{}/\cfuncref{PL_discard_foreign_frame}{}. A \ctype{term_t} always refers to a valid Prolog term (variable, atom, integer, float or compound term). A term lives either until backtracking takes us back to a point before the term was created, the garbage collector has collected the term, or the term was created after a \cfuncref{PL_open_foreign_frame}{} and \cfuncref{PL_discard_foreign_frame}{} has been called. The foreign interface functions can either \textit{read}, \textit{unify} or \textit{write} to term references. In this document we use the following notation for arguments of type \ctype{term_t}: \begin{quote} \begin{tabular}{lp{4in}} \tt term_t +t & Accessed in read-mode. The `+' indicates the argument is `input'. \\ \tt term_t -t & Accessed in write-mode. \\ \tt term_t ?t & Accessed in unify-mode. \\ \end{tabular} \end{quote} \textbf{WARNING} Term references that are accessed in `write' (-) mode will refer to an invalid term if the term is allocated on the global stack and backtracking takes us back to a point before the term was written.\footnote{This could have been avoided by \jargon{trailing} term references when data is written to them. This seriously hurts performance in some scenarios though. If this is desired, use \cfuncref{PL_put_variable}{} followed by one of the PL_unify_*() functions.} Compound terms, dicts, large integers, rational numbers, floats and strings are all allocated on the global stack. Below is a typical scenario where this may happen. The first solution writes a term extracted from the solution into \arg{a}. After the system backtracks due to \cfuncref{PL_next_solution}{}, \arg{a} becomes a reference to a term that no longer exists. \begin{code} term_t a = PL_new_term_ref(); ... query = PL_open_query(...); while(PL_next_solution(query)) { PL_get_arg(i, ..., a); } PL_close_query(query); \end{code} \noindent There are two solutions to this problem. One is to scope the term reference using \cfuncref{PL_open_foreign_frame}{} and \cfuncref{PL_close_foreign_frame}{} and makes sure it goes out of scope before backtracking happens. The other is to clear the term reference using \cfuncref{PL_put_variable}{} before backtracking. Term references are obtained in any of the following ways: \begin{itemlist} \item [Passed as argument] The C functions implementing foreign predicates are passed their arguments as term references. These references may be read or unified. Writing to these variables causes undefined behaviour. \item [Created by \cfuncref{PL_new_term_ref}{}] A term created by \cfuncref{PL_new_term_ref}{} is normally used to build temporary terms or to be written by one of the interface functions. For example, \cfuncref{PL_get_arg}{} writes a reference to the term argument in its last argument. \item [Created by \cfuncref{PL_new_term_refs}{int n}] This function returns a set of term references with the same characteristics as \cfuncref{PL_new_term_ref}{}. See \cfuncref{PL_open_query}{}. \item [Created by \cfuncref{PL_copy_term_ref}{term_t t}] Creates a new term reference to the same term as the argument. The term may be written to. See \figref{pl-display}. \end{itemlist} Term references can safely be copied to other C variables of type \ctype{term_t}, but all copies will always refer to the same term. \begin{description} \cfunction{term_t}{PL_new_term_ref}{} Return a fresh reference to a term. The reference is allocated on the \jargon{local} stack. Allocating a term reference may trigger a stack-shift on machines that cannot use sparse memory management for allocation of the Prolog stacks. The returned reference describes a variable. Raise a resource exception and returns \exam{(term_t)0} on failure. \cfunction{term_t}{PL_new_term_refs}{int n} Return \arg{n} new term references. The first term reference is returned. The others are $\arg{t}+1$, $\arg{t}+2$, etc. Raise a resource exception and returns \exam{(term_t)0} on failure. There are two reasons for using this function. \cfuncref{PL_open_query}{} and \cfuncref{PL_cons_functor}{} expect the arguments as a set of consecutive term references, and \emph{very} time-critical code requiring a number of term references can be written as: \begin{code} pl_mypredicate(term_t a0, term_t a1) { term_t t0 = PL_new_term_refs(2); term_t t1 = t0+1; ... } \end{code} \noindent \cfunction{term_t}{PL_copy_term_ref}{term_t from} Create a new term reference and make it point initially to the same term as \arg{from}. This function is commonly used to copy a predicate argument to a term reference that may be written. Raise a resource exception and returns \exam{(term_t)0} on failure. An example of its use is given below, in the sample code \exam{pl_write_atoms()}. \cfunction{void}{PL_reset_term_refs}{term_t after} Destroy all term references that have been created after \arg{after}, including \arg{after} itself. Any reference to the invalidated term references after this call results in undefined behaviour. Note that returning from the foreign context to Prolog will reclaim all references used in the foreign context. This call is only necessary if references are created inside a loop that never exits back to Prolog. See also \cfuncref{PL_open_foreign_frame}{}, \cfuncref{PL_close_foreign_frame}{} and \cfuncref{PL_discard_foreign_frame}{}. \end{description} \subsubsection{Interaction with the garbage collector and stack-shifter} \label{sec:foreign-gc} Prolog implements two mechanisms for avoiding stack overflow: garbage collection and stack expansion. On machines that allow for it, Prolog will use virtual memory management to detect stack overflow and expand the runtime stacks. On other machines Prolog will reallocate the stacks and update all pointers to them. To do so, Prolog needs to know which data is referenced by C code. As all Prolog data known by C is referenced through term references (\ctype{term_t}), Prolog has all the information necessary to perform its memory management without special precautions from the C programmer. \subsection{Other foreign interface types} \label{sec:foreign-types} \begin{description} \item[atom_t] The type \ctype{atom_t} actually represents a \jargon{blob} (see \secref{blob}). Blobs are the super type of Prolog atoms, where atoms are blobs that represent textual content. Textual content is also represented by Prolog string (see \secref{string}), which makes the general notion of \jargon{string} in Prolog ambiguous. The core idea behind blobs/atoms is to represent arbitrary content using a \emph{unique} handle, such that comparing the handle is enough to prove equivalence of the content; i.e., given two different atom handles we know they represent different texts. This uniqueness feature allows the core engine to reason about atoms without considering their content. \jargon{Strings} (\secref{string}) and blobs without the \const{PL_BLOB_UNIQUE} feature do \emph{not} have this uniqueness property - to test for equality, the contents of the strings or blobs must be compared. Because atoms are often used to represent (parts of) arbitrary input, intermediate results, and output of data processed by Prolog, it is necessary that atoms be subject to \jargon{garbage collection} (see \index{garbage_collect_atoms/0}\predref{garbage_collect_atoms}{0}). The garbage collection makes atoms ideal handles for arbitrary data structures, which are generalized as \jargon{blobs}. Blobs provide \emph{safe} access to many internal Prolog data structures such as streams, clause references, etc. \item[functor_t] A functor is the internal representation of a name/arity pair. They are used to find the name and arity of a compound term as well as to construct new compound terms. Like atoms they live for the whole Prolog session and are unique. \item[predicate_t] Handle to a Prolog predicate. Predicate handles live forever (although they can lose their definition). \item[qid_t] Query identifier. Used by \cfuncref{PL_open_query}{}, \cfuncref{PL_next_solution}{}, \cfuncref{PL_cut_query}{}, and \cfuncref{PL_close_query}{} to handle calling Prolog from C. \item[fid_t] Frame identifier. Used by \cfuncref{PL_open_foreign_frame}{} and \cfuncref{PL_close_foreign_frame}{}. \item[module_t] A module is a unique handle to a Prolog module. Modules are used only to call predicates in a specific module. \item[foreign_t] Return type for a C function implementing a Prolog predicate. \item[control_t] Passed as additional argument to non-deterministic foreign functions. See PL_retry*() and PL_foreign_context*(). \item[install_t] Type for the install() and uninstall() functions of shared or dynamic link libraries. See \secref{shlib}. \item[int64_t] Actually part of the C99 standard rather than Prolog. As of version 5.5.6, Prolog integers are 64-bit on all hardware. The C99 type \ctype{int64_t} is defined in the \file{stdint.h} standard header and provides platform-independent 64-bit integers. Portable code accessing Prolog should use this type to exchange integer values. Please note that \cfuncref{PL_get_long}{} can return \const{FALSE} on Prolog integers that cannot be represented as a C long. Robust code should not assume any of the integer fetching functions to succeed, \emph{even} if the Prolog term is known to be an integer. \end{description} \subsubsection{PL_ARITY_AS_SIZE} \label{sec:pl-arity-as-size} As of SWI-Prolog 7.3.12, the arity of terms has changed from \ctype{int} to \ctype{size_t}. To deal with this transition, all affecting functions have two versions, where the old name exchanges the arity as \ctype{int} and a new function with name *_sz() exchanges the arity as \ctype{size_t}. Up to 8.1.28, the default was to use the old \ctype{int} functions. As of 8.1.29/8.2.x, the default is to use \ctype{size_t} and the old behaviour can be restored by defining \const{PL_ARITY_AS_SIZE} to \const{0} (zero). This makes old code compatible, but the following warning is printed when compiling: \begin{code} #warning "Term arity has changed from int to size_t." #warning "Please update your code or use #define PL_ARITY_AS_SIZE 0." \end{code} \noindent To make the code compile silently again, change the types you use to represent arity from \ctype{int} to \ctype{size_t}. Please be aware that \ctype{size_t} is \emph{unsigned}. At some point representing arity as \ctype{int} will be dropped completely. \section{The Foreign Include File} \label{sec:foreigninclude} \subsection{Argument Passing and Control} \label{sec:foreign-control} If Prolog encounters a foreign predicate at run time it will call a function specified in the predicate definition of the foreign predicate. The arguments $1, \ldots, \bnfmeta{arity}$ pass the Prolog arguments to the goal as Prolog terms. Foreign functions should be declared of type \ctype{foreign_t}. All the arguments to a foreign predicate must be of type \ctype{term_t}. The only operation that is allowed with an argument to a foreign predicate is unification; for anything that might over-write the term, you must use a copy created by \cfuncref{PL_copy_term_ref}{}. For an example, see \cfuncref{PL_unify_list}{}. Deterministic foreign functions have two alternatives to return control back to Prolog: \begin{description} \cmacro{(return) foreign_t}{PL_succeed}{} Succeed deterministically. PL_succeed is defined as \exam{return \const{TRUE}}. \cmacro{(return) foreign_t}{PL_fail}{} Fail and start Prolog backtracking. PL_fail is defined as \exam{return \const{FALSE}}. \end{description} \subsubsection{Non-deterministic Foreign Predicates} \label{sec:foreignnondet} By default foreign predicates are deterministic. Using the \const{PL_FA_NONDETERMINISTIC} attribute (see \cfuncref{PL_register_foreign}{}) it is possible to register a predicate as a non-deterministic predicate. Writing non-deterministic foreign predicates is slightly more complicated as the foreign function needs context information for generating the next solution. Note that the same foreign function should be prepared to be simultaneously active in more than one goal. Suppose the {natural_number_below_n}/2 is a non-deterministic foreign predicate, backtracking over all natural numbers lower than the first argument. Now consider the following predicate: \begin{code} quotient_below_n(Q, N) :- natural_number_below_n(N, N1), natural_number_below_n(N, N2), Q =:= N1 / N2, !. \end{code} \noindent In this predicate the function {natural_number_below_n}/2 simultaneously generates solutions for both its invocations. Non-deterministic foreign functions should be prepared to handle three different calls from Prolog: \begin{itemlist} \item [Initial call (\const{PL_FIRST_CALL})] Prolog has just created a frame for the foreign function and asks it to produce the first answer. \item [Redo call (\const{PL_REDO})] The previous invocation of the foreign function associated with the current goal indicated it was possible to backtrack. The foreign function should produce the next solution. \item [Terminate call (\const{PL_PRUNED})] The choice point left by the foreign function has been destroyed by a cut or exception. The foreign function is given the opportunity to clean the environment. The context handle is the only meaningful argument -- the term arguments to the call are \exam{(term_t)0}. \end{itemlist} Both the context information and the type of call is provided by an argument of type \ctype{control_t} appended to the argument list for deterministic foreign functions. The macro \cfuncref{PL_foreign_control}{} extracts the type of call from the control argument. The foreign function can pass a context handle using the {\tt PL_retry*()} macros and extract the handle from the extra argument using the {\tt PL_foreign_context*()} macro. \begin{description} \cmacro{(return) foreign_t}{PL_retry}{intptr_t value} The foreign function succeeds while leaving a choice point. On backtracking over this goal the foreign function will be called again, but the control argument now indicates it is a `Redo' call and the macro \cfuncref{PL_foreign_context}{} returns the handle passed via \cfuncref{PL_retry}{}. This handle is a signed value two bits smaller than a pointer, i.e., 30 or 62 bits (two bits are used for status indication). Defined as \exam{return _\cfuncref{PL_retry}{n}}. See also \cfuncref{PL_succeed}{}. \cmacro{(return) foreign_t}{PL_retry_address}{void *} As \cfuncref{PL_retry}{}, but ensures an address as returned by malloc() is correctly recovered by \cfuncref{PL_foreign_context_address}{}. Defined as \exam{return _\cfuncref{PL_retry_address}{n}}. See also \cfuncref{PL_succeed}{}. \cmacro{int}{PL_foreign_control}{control_t} Extracts the type of call from the control argument. The return values are described above. Note that the function should be prepared to handle the \const{PL_PRUNED} case and should be aware that the other arguments are not valid in this case. \cmacro{intptr_t}{PL_foreign_context}{control_t} Extracts the context from the context argument. If the call type is \const{PL_FIRST_CALL} the context value is 0L. Otherwise it is the value returned by the last \cfuncref{PL_retry}{} associated with this goal (both if the call type is \const{PL_REDO} or \const{PL_PRUNED}). \cmacro{void *}{PL_foreign_context_address}{control_t} Extracts an address as passed in by \cfuncref{PL_retry_address}{}. \cmacro{predicate_t}{PL_foreign_context_predicate}{control_t} Fetch the Prolog predicate that is executing this function. Note that if the predicate is imported, the returned predicate refers to the final definition rather than the imported predicate; i.e., the module reported by \cfuncref{PL_predicate_info}{} is the module in which the predicate is defined rather than the module where it was called. See also \cfuncref{PL_predicate_info}{}. \end{description} Note: If a non-deterministic foreign function returns using \cfuncref{PL_succeed}{} or \cfuncref{PL_fail}{}, Prolog assumes the foreign function has cleaned its environment. {\bf No} call with control argument \const{PL_PRUNED} will follow. The code of \figref{nondetermf} shows a skeleton for a non-deterministic foreign predicate definition. \begin{figure} \begin{code} typedef struct /* define a context structure */ { ... } context; foreign_t my_function(term_t a0, term_t a1, control_t handle) { struct context * ctxt; switch( PL_foreign_control(handle) ) { case PL_FIRST_CALL: if ( !(ctxt = malloc(sizeof *ctxt)) ) return PL_resource_error("memory"); break; case PL_REDO: ctxt = PL_foreign_context_address(handle); break; case PL_PRUNED: ctxt = PL_foreign_context_address(handle); ... free(ctxt); return TRUE; } ... // We fail */ if ( ) { free(ctx); return FALSE; } // We succeed without a choice point */ if ( ) { free(ctx); return TRUE; } // We succeed with a choice point */ PL_retry_address(ctxt); } \end{code} \noindent \caption{Skeleton for non-deterministic foreign functions} \label{fig:nondetermf} \end{figure} \subsubsection{Yielding from foreign predicates} \label{sec:foreign-yield} Starting with SWI-Prolog 8.5.5 we provide an experimental interface that allows using a SWI-Prolog engine for asynchronous processing. The idea is that an engine that calls a foreign predicate which would need to block may be suspended and later resumed. For example, consider an application that listens to a large number of network connections (sockets). SWI-Prolog offers three scenarios to deal with this: \begin{enumerate} \item Using a thread per connection. This model fits Prolog well as it allows to keep state in e.g. a DCG using \index{phrase_from_stream/2}\predref{phrase_from_stream}{2}. Maintaining an operating system thread per connection uses a significant amount of resources though. \item Using \index{wait_for_input/3}\predref{wait_for_input}{3} a single thread can wait for many connections. Each time input arrives we must associate this with a \jargon{state engine} and advance this engine using a chunk of input of unknown size. Programming a state engine in Prolog is typically a tedious job. Although we can use \jargon{delimited continuations} (see \secref{delcont}) in some scenarios this is not a universal solution. \item Using the primitives from this section we can create an \jargon{engine} (see \cfuncref{PL_engine_create}{}) to handle a connection with the same benefits as using threads. When the engine calls a foreign predicate that would need to block it calls \cfuncref{PL_yield_address}{} to suspend the engine. An overall scheduler watches for ready connections and calls \cfuncref{PL_next_solution}{} to resume the suspended engine. This approach allows processing many connections on the same operating system thread. \end{enumerate} As is, these features can only used through the foreign language interface. It was added after discussion with with Mattijs van Otterdijk aiming for using SWI-Prolog together with Rust's \href{https://rust-lang.github.io/async-book/01_getting_started/01_chapter.html}{asynchronous programming} support. Note that this feature is related to the engine API as described in \secref{engines}. It uis different though. Where the Prolog engine API allows for communicating with a Prolog engine, the facilities of this section merely allow an engine to suspend, to be resumed later. To prepare a query for asynchronous usage we first create an engine using \cfuncref{PL_create_engine}{}. Next, we create a query in the engine using \cfuncref{PL_open_query}{} with the flags \const{PL_Q_ALLOW_YIELD} and \const{PL_Q_EXT_STATUS}. A foreign predicate that needs to be capable of suspending must be registered using \cfuncref{PL_register_foreign}{} and the flags \const{PL_FA_VARARGS} and \const{PL_FA_NONDETERMINISTIC}; i.e., only non-det predicates can yield. This is no restriction as non-det predicate can always return \const{TRUE} to indicate deterministic success. Finally, \cfuncref{PL_yield_address}{} allows the predicate to yield control, preparing to resume similar to \cfuncref{PL_retry_address}{} does for non-deterministic results. \cfuncref{PL_next_solution}{} returns \const{PL_S_YIELD} if a predicate calls \cfuncref{PL_yield_address}{} and may be resumed by calling \cfuncref{PL_next_solution}{} using the same query id (\arg{qid}). We illustrate the above using some example fragments. First, let us create a predicate that can read the available input from a Prolog stream and yield if it would block. Note that our predicate \emph{must} the \const{PL_FA_VARARGS} interface, which implies the first argument is in \arg{a0}, the second in \exam{a0+1}, etc.\footnote{the other foreign interfaces do not support the yield API.} \begin{code} /** read_or_block(+Stream, -String) is det. */ #define BUFSIZE 4096 static foreign_t read_or_block(term_t a0, int arity, void *context) { IOSTREAM *s; switch(PL_foreign_control(context)) { case PL_FIRST_CALL: if ( PL_get_stream(a0, &s, SIO_INPUT) ) { Sset_timeout(s, 0); break; } return FALSE; case PL_RESUME: s = PL_foreign_context_address(context); break; case PL_PRUNED: PL_release_stream(s); return TRUE; default: assert(0); return FALSE; } char buf[BUFSIZE]; size_t n = Sfread(buf, sizeof buf[0], sizeof buf / sizeof buf[0], s); if ( n == 0 ) // timeout or error { if ( (s->flags&SIO_TIMEOUT) ) PL_yield_address(s); // timeout: yield else return PL_release_stream(s); // raise error } else { PL_release_stream(s); return PL_unify_chars(a0+1, PL_STRING|REP_ISO_LATIN_1, n, buf); } } \end{code} \noindent This function must be registered using \cfuncref{PL_register_foreign}{}: \begin{code} PL_register_foreign("read_or_block", 2, read_or_block, PL_FA_VARARGS|PL_FA_NONDETERMINISTIC); \end{code} \noindent Next, create an engine to run \nopredref{handle_connection}{1} on a Prolog stream. Note that we omitted most of the error checking for readability. Also note that we must make our engine \emph{current} using \cfuncref{PL_set_engine}{} before we can interact with it. \begin{code} qid_t start_connection(IOSTREAM *c) { predicate_t p = PL_predicate("handle_connection", 1, "user"); PL_engine_t e = PL_create_engine(NULL); PL_engine_t old; if ( PL_set_engine(e, &old) ) { term_t av = PL_new_term_refs(1); PL_unify_stream(av+0, c); qid_t q = PL_open_query(e, NULL, PL_Q_CATCH_EXCEPTION| PL_Q_ALLOW_YIELD| PL_Q_EXT_STATUS, p, av); PL_set_engine(old, NULL); return q; } /* else error */ } \end{code} \noindent Finally, our foreign code must manage this engine. Normally it will do so together with many other engines. First, we write a function that runs a query in the engine to which it belongs.\footnote{Possibly, future versions of \cfuncref{PL_next_solution}{} may do that although the value is in general limited because interacting with the arguments of the query requires the query's engine to be current anyway.} \begin{code} int PL_engine_next_solution(qid_t qid) { PL_engine_t old; int rc; if ( PL_set_engine(PL_query_engine(qid), &old) == PL_ENGINE_SET ) { rc = PL_next_solution(qid); PL_set_engine(old, NULL); } else rc = FALSE; return rc; } \end{code} \noindent Now we can simply handle a connection using the loop below which restarts the query as long as it yields. Realistic code manages multiple queries and will (in this case) use the POSIX poll() or select() interfaces to activate the next query that can continue without blocking. \begin{code} int rc; do { rc = PL_engine_next_solution(qid); } while( rc == PL_S_YIELD ); \end{code} \noindent After the query completes it must be closed using \cfuncref{PL_close_query}{} or \cfuncref{PL_cut_query}{}. The engine may be destroyed using \cfuncref{PL_engine_destroy}{} or reused for a new query. \begin{description} \cmacro{(return) foreign_t}{PL_yield_address}{void *} Cause \cfuncref{PL_next_solution}{} of the active query to return with \const{PL_S_YIELD}. A subsequent call to \cfuncref{PL_next_solution}{} on the same query calls the foreign predicate again with the control status set to \const{PL_RESUME}, after which \cfuncref{PL_foreign_context_address}{} retrieves the address passed to this function. The state of the Prolog engine is maintained, including \ctype{term_t} handles. If the passed address needs to be invalidated the predicate must do so when returning either \const{TRUE} or \const{FALSE}. If the engine terminates the predicate the predicate is called with status \const{PL_PRUNED}, in which case the predicate must cleanup. \cfunction{int}{PL_can_yield}{void} Returns \const{TRUE} when called from inside a foreign predicate if the query that (indirectly) calls this foreign predicate can yield using \cfuncref{PL_yield_address}{}. Returns \const{FALSE} when either there is no current query or the query cannot yield. \end{description} \paragraph{Discussion} Asynchronous processing has become popular with modern programming languages, especially those aiming at network communication. Asynchronous processing uses fewer resources than threads while avoiding most of the complications associated with thread synchronization if only a single thread is used to manage the various states. The lack of good support for destructive state updates in Prolog makes it attractive to use threads for dealing with multiple inputs. The fact that Prolog discourages using shared global data such as dynamic predicates typically makes multithreaded code easy to manage. It is not clear how much scalability we gain using Prolog engines instead of Prolog threads. The only difference between the two is the operating system task. Prolog engines are still rather memory intensive, mainly depending on the stack sizes. Global garbage collection (atoms and clauses) need to process all the stacks of all the engines and thus limit scalability. One possible future direction is to allow all (possibly) blocking Prolog predicates to use the yield facility and provide a Prolog API to manage sets of engines that use this type of yielding. As is, these features are designed to allow SWI-Prolog for cooperating with languages that provide asynchronous functions. \subsection{Atoms and functors} \label{sec:foreign-atoms} The following functions provide for communication using atoms and functors. \begin{description} \cfunction{atom_t}{PL_new_atom}{const char *} Return an atom handle for the given C-string. This function always succeeds. The returned handle is valid as long as the atom is referenced (see \secref{atomgc}). Currently aborts the process with a \jargon{fatal error} on failure. Future versions may raise a resource exception and return \exam{(atom_t)0}. The following atoms are provided as macros, giving access to the empty list symbol and the name of the list constructor. Prior to version~7, \const{ATOM_nil} is the same as \exam{\cfuncref{PL_new_atom}{"[]"}} and \const{ATOM_dot} is the same as \exam{\cfuncref{PL_new_atom}{"."}}. This is no longer the case in SWI-Prolog version~7. \begin{description} \cmacro{atom_t}{ATOM_nil} Atomic constant that represents the empty list. It is advised to use \cfuncref{PL_get_nil}{}, \cfuncref{PL_put_nil}{} or \cfuncref{PL_unify_nil}{} where applicable. \cmacro{atom_t}{ATOM_dot} Atomic constant that represents the name of the list constructor. The list constructor itself is created using \exam{\cfuncref{PL_new_functor}{ATOM_dot,2}}. It is advised to use \cfuncref{PL_get_list}{}, \cfuncref{PL_put_list}{} or \cfuncref{PL_unify_list}{} where applicable. \end{description} \cfunction{atom_t}{PL_new_atom_mbchars}{int rep, size_t len, const char *s} This function generalizes \cfuncref{PL_new_atom}{} and \cfuncref{PL_new_atom_nchars}{} while allowing for multiple encodings. The \arg{rep} argument is one of \const{REP_ISO_LATIN_1}, \const{REP_UTF8} or \const{REP_MB}. If \arg{len} is \exam{(size_t)-1}, it is computed from \arg{s} using strlen(). Raises an exception if \arg{s} violates \arg{rep} and returns \exam{(atom_t)0}. For other error conditions, see \cfuncref{PL_new_atom}{}. \cfunction{int}{PL_atom_mbchars}{atom_t atom, size_t len, char *s, unsigned int flags} This function generalizes fetching the text associated with an atom. The encoding depends on the flags \const{REP_UTF8}, \const{REP_MB} or \const{REP_ISO_LATIN_1}. Storage is defined by the \const{BUF_*} flags as described with \cfuncref{PL_get_chars}{}. The flag \const{CVT_EXCEPTION} defines whether or not the function fails silently or raises a Prolog exception. This function may fail because \arg{atom} is not a text atom but a \jargon{blob} (see \secref{blob}), conversion to the requested encoding is not possible or a resource error occurs. \cfunction{const char*}{PL_atom_chars}{atom_t atom} Deprecated. This function returns a pointer to the content represented by the atom or blob regardless of its type. New code that uses blobs should use the blob functions such as \cfuncref{PL_blob_data}{} to get a pointer to the content, the size of the content, and the type of the content. Most applications that need to get text from a \ctype{term_t} handle should use \cfuncref{PL_atom_nchars}{}, \cfuncref{PL_atom_wchars}{}, or \cfuncref{PL_atom_mbchars}{}. If it is \emph{known} that \arg{atom} is a classical Prolog text atom, one can use \cfuncref{PL_atom_nchars}{} to obtain the C string and its length (for ISO-Latin-1 atoms) or \cfuncref{PL_atom_wchars}{} to obtain a C wide string (\ctype{wchar_t}). \cfunction{functor_t}{PL_new_functor}{atom_t name, int arity} Returns a {\em functor identifier}, a handle for the name/arity pair. The returned handle is valid for the entire Prolog session. Future versions may garbage collect functors as part of atom garbage collection. Currently aborts the process with a \jargon{fatal error} on failure. Future versions may raise a resource exception and return \exam{(atom_t)0}. \cfunction{atom_t}{PL_functor_name}{functor_t f} Return an atom representing the name of the given functor. \cfunction{size_t}{PL_functor_arity}{functor_t f} Return the arity of the given functor. \end{description} \subsubsection{Atoms and atom garbage collection} \label{sec:atomgc} With the introduction of atom garbage collection in version 3.3.0, atoms no longer live as long as the process. Instead, their lifetime is guaranteed only as long as they are referenced. In the single-threaded version, atom garbage collections are only invoked at the \jargon{call-port}. In the multithreaded version (see \chapref{threads}), they appear asynchronously, except for the invoking thread. For dealing with atom garbage collection, two additional functions are provided: \begin{description} \cfunction{void}{PL_register_atom}{atom_t atom} Increment the reference count of the atom by one. \cfuncref{PL_new_atom}{} performs this automatically, returning an atom with a reference count of at least one.% \footnote{Otherwise asynchronous atom garbage collection might destroy the atom before it is used.} \cfunction{void}{PL_unregister_atom}{atom_t atom} Decrement the reference count of the atom. If the reference count drops below zero, an assertion error is raised. \end{description} Please note that the following two calls are different with respect to atom garbage collection: \begin{code} PL_unify_atom_chars(t, "text"); PL_unify_atom(t, PL_new_atom("text")); \end{code} \noindent The latter increments the reference count of the atom \const{text}, which effectively ensures the atom will never be collected. It is advised to use the *_chars() or *_nchars() functions whenever applicable. \subsection{Analysing Terms via the Foreign Interface} \label{sec:foreign-term-analysis} Each argument of a foreign function (except for the control argument) is of type \ctype{term_t}, an opaque handle to a Prolog term. Three groups of functions are available for the analysis of terms. The first just validates the type, like the Prolog predicates \index{var/1}\predref{var}{1}, \index{atom/1}\predref{atom}{1}, etc., and are called {\tt PL_is_*()}. The second group attempts to translate the argument into a C primitive type. These predicates take a \ctype{term_t} and a pointer to the appropriate C type and return \const{TRUE} or \const{FALSE} depending on successful or unsuccessful translation. If the translation fails, the pointed-to data is never modified. \subsubsection{Testing the type of a term} \label{sec:foreign-term-type} \begin{description} \cfunction{int}{PL_term_type}{term_t} Obtain the type of a term, which should be a term returned by one of the other interface predicates or passed as an argument. The function returns the type of the Prolog term. The type identifiers are listed below. Note that the extraction functions {\tt PL_get_*()} also validate the type and thus the two sections below are equivalent. \begin{code} if ( PL_is_atom(t) ) { char *s; PL_get_atom_chars(t, &s); ...; } or char *s; if ( PL_get_atom_chars(t, &s) ) { ...; } \end{code} \noindent \textbf{Version~7} added \const{PL_NIL}, \const{PL_BLOB}, \const{PL_LIST_PAIR} and \const{PL_DICT}. Older versions classify \const{PL_NIL} and \const{PL_BLOB} as \const{PL_ATOM}, \const{PL_LIST_PAIR} as \const{PL_TERM} and do not have dicts. \begin{tabular}{|p{\tableft}|p{\linewidth-\tableft-2cm}|} \hline \const{PL_VARIABLE} & A variable or attributed variable \\ \const{PL_ATOM} & A Prolog atom \\ \const{PL_NIL} & The constant \verb$[]$ \\ \const{PL_BLOB} & A blob (see \secref{blobaccess}) \\ \const{PL_STRING} & A string (see \secref{string}) \\ \const{PL_INTEGER} & A integer \\ \const{PL_RATIONAL} & A rational number \\ \const{PL_FLOAT} & A floating point number \\ \const{PL_TERM} & A compound term \\ \const{PL_LIST_PAIR} & A list cell (\verb$[H|T]$) \\ \const{PL_DICT} & A dict (see \secref{bidicts})) \\ \hline \end{tabular} \end{description} The functions PL_is_\bnfmeta{type} are an alternative to \cfuncref{PL_term_type}{}. The test \exam{\cfuncref{PL_is_variable}{term}} is equivalent to \exam{\cfuncref{PL_term_type}{term} == PL_VARIABLE}, but the first is considerably faster. On the other hand, using a switch over \cfuncref{PL_term_type}{} is faster and more readable then using an if-then-else using the functions below. All these functions return either \const{TRUE} or \const{FALSE}. \begin{description} \cfunction{int}{PL_is_variable}{term_t} Returns non-zero if \arg{term} is a variable. \cfunction{int}{PL_is_ground}{term_t} Returns non-zero if \arg{term} is a ground term. See also \index{ground/1}\predref{ground}{1}. This function is cycle-safe. \cfunction{int}{PL_is_atom}{term_t} Returns non-zero if \arg{term} is an atom. \cfunction{int}{PL_is_string}{term_t} Returns non-zero if \arg{term} is a string. \cfunction{int}{PL_is_integer}{term_t} Returns non-zero if \arg{term} is an integer. \cfunction{int}{PL_is_rational}{term_t} Returns non-zero if \arg{term} is a rational number ($P/Q$). Note that all integers are considered rational and this test thus succeeds for any term for which \cfuncref{PL_is_integer}{} succeeds. See also \cfuncref{PL_get_mpq}{} and \cfuncref{PL_unify_mpq}{}. \cfunction{int}{PL_is_float}{term_t} Returns non-zero if \arg{term} is a float. Note that the corresponding \cfuncref{PL_get_float}{} converts rationals (and thus integers). \cfunction{int}{PL_is_callable}{term_t} Returns non-zero if \arg{term} is a callable term. See \index{callable/1}\predref{callable}{1} for details. \cfunction{int}{PL_is_compound}{term_t} Returns non-zero if \arg{term} is a compound term. \cfunction{int}{PL_is_functor}{term_t, functor_t} Returns non-zero if \arg{term} is compound and its functor is \arg{functor}. This test is equivalent to \cfuncref{PL_get_functor}{}, followed by testing the functor, but easier to write and faster. \cfunction{int}{PL_is_list}{term_t} Returns non-zero if \arg{term} is a compound term using the list constructor or the list terminator. See also \cfuncref{PL_is_pair}{} and \cfuncref{PL_skip_list}{}. \cfunction{int}{PL_is_pair}{term_t} Returns non-zero if \arg{term} is a compound term using the list constructor. See also \cfuncref{PL_is_list}{} and \cfuncref{PL_skip_list}{}. \cfunction{int}{PL_is_dict}{term_t} Returns non-zero if \arg{term} is a dict. See also \cfuncref{PL_put_dict}{} and \cfuncref{PL_get_dict_key}{}. \cfunction{int}{PL_is_atomic}{term_t} Returns non-zero if \arg{term} is atomic (not a variable or compound). \cfunction{int}{PL_is_number}{term_t} Returns non-zero if \arg{term} is an rational (including integers) or float. \cfunction{int}{PL_is_acyclic}{term_t} Returns non-zero if \arg{term} is acyclic (i.e.\ a finite tree). \end{description} \subsubsection{Reading data from a term} \label{sec:foreign-extract-from-term} The functions {\tt PL_get_*()} read information from a Prolog term. Most of them take two arguments. The first is the input term and the second is a pointer to the output value or a term reference. The return value is \const{TRUE} or \const{FALSE}, indicating the success of the "get" operation. Most functions have a related "_ex" function that raises an error if the argument is the operation cannot be completed. If the Prolog term is not suitable, this is a type, domain or instantiation error. If the receiving C type cannot represent the value this is a representation error. For integers an alternative interface exists, which helps deal with the various integer types in C and C++. They are convenient for use with \exam{_Generic} selection or C++ overloading. \begin{description} \cfunction{int}{PL_get_atom}{term_t +t, atom_t *a} If \arg{t} is an atom, store the unique atom identifier over \arg{a}. See also \cfuncref{PL_atom_chars}{} and \cfuncref{PL_new_atom}{}. If there is no need to access the data (characters) of an atom, it is advised to manipulate atoms using their handle. As the atom is referenced by \arg{t}, it will live at least as long as \arg{t} does. If longer lifetime is required, the atom should be locked using \cfuncref{PL_register_atom}{}. \cfunction{int}{PL_get_atom_chars}{term_t +t, char **s} If \arg{t} is an atom, store a pointer to a 0-terminated C-string in \arg{s}. It is explicitly \strong{not} allowed to modify the contents of this string. Some built-in atoms may have the string allocated in read-only memory, so `temporary manipulation' can cause an error. \cfunction{int}{PL_get_string_chars}{term_t +t, char **s, size_t *len} If \arg{t} is a string object, store a pointer to a 0-terminated C-string in \arg{s} and the length of the string in \arg{len}. Note that this pointer is invalidated by backtracking, garbage collection and stack-shifts, so generally the only safe operations are to pass it immediately to a C function that doesn't involve Prolog. \cfunction{int}{PL_get_chars}{term_t +t, char **s, unsigned flags} Convert the argument term \arg{t} to a 0-terminated C-string. \arg{flags} is a bitwise disjunction from two groups of constants. The first specifies which term types should be converted and the second how the argument is stored. Below is a specification of these constants. \const{BUF_STACK} implies, if the data is not static (as from an atom), that the data is pushed on a stack. If BUF_MALLOC is used, the data must be freed using \cfuncref{PL_free}{} when no longer needed. With the introduction of wide characters (see \secref{encoding}), not all atoms can be converted into a \ctype{char*}. This function fails if \arg{t} is of the wrong type, but also if the text cannot be represented. See the \const{REP_*} flags below for details. See also \cfuncref{PL_get_wchars}{} and \cfuncref{PL_get_nchars}{}. \begin{description} \termitem{CVT_ATOM}{} Convert if term is an atom. \termitem{CVT_STRING}{} Convert if term is a string. \termitem{CVT_LIST}{} Convert if term is a list of of character codes. \termitem{CVT_INTEGER}{} Convert if term is an integer. \termitem{CVT_RATIONAL}{} Convert if term is an rational number. The number is written as \bnfmeta{num}r\bnfmeta{den}. \termitem{CVT_XINTEGER}{} Convert if term is an integer to hexadecimal notation. May be combined with \const{CVT_RATIONAL} to represent rational numbers using hexadecimal notation. Hexadecimal notation is notably useful for transferring big integers to other programming environments if the target system can read hexadecimal notation because the result is both more compact and faster to write and read. \termitem{CVT_FLOAT}{} Convert if term is a float. The characters returned are the same as \index{write/1}\predref{write}{1} would write for the floating point number. \termitem{CVT_NUMBER}{} Convert if term is an integer, rational number or or float. Equivalent to \mbox{\const{CVT_INTEGER}{\Sbar}\const{CVT_RATIONAL}{\Sbar}\const{CVT_FLOAT}} \termitem{CVT_ATOMIC}{} Convert if term is atomic. \termitem{CVT_VARIABLE}{} Convert variable to print-name \termitem{CVT_WRITE}{} Convert any term that is not converted by any of the other flags using \index{write/1}\predref{write}{1}. If no \const{BUF_*} is provided, \const{BUF_STACK} is implied. \termitem{CVT_WRITE_CANONICAL}{} As \const{CVT_WRITE}, but using \index{write_canonical/2}\predref{write_canonical}{2}. \termitem{CVT_WRITEQ}{} As \const{CVT_WRITE}, but using \index{writeq/2}\predref{writeq}{2}. \termitem{CVT_ALL}{} Convert if term is any of the above, except for \const{CVT_VARIABLE} and \const{CVT_WRITE*}. \termitem{CVT_EXCEPTION}{} If conversion fails due to a type error, raise a Prolog type error exception in addition to failure \termitem{BUF_DISCARDABLE}{} Data must copied immediately. \termitem{BUF_STACK}{} Data is stored on a stack. The older \const{BUF_RING} is an alias for \const{BUF_STACK}. See \secref{foreign-strings}. \termitem{BUF_MALLOC}{} Data is copied to a new buffer returned by \manref{PL_malloc}{3}. When no longer needed the user must call \cfuncref{PL_free}{} on the data. \termitem{REP_ISO_LATIN_1}{} Text is in ISO Latin-1 encoding and the call fails if text cannot be represented. This flag has the value 0 and is thus the default. \termitem{REP_UTF8}{} Convert the text to a UTF-8 string. This works for all text. \termitem{REP_MB}{} Convert to default locale-defined 8-bit string. Success depends on the locale. Conversion is done using the wcrtomb() C library function. \end{description} \cfunction{int}{PL_get_list_chars}{+term_t l, char **s, unsigned flags} Same as \exam{\cfuncref{PL_get_chars}{\arg{l}, \arg{s}, CVT_LIST|\arg{flags}}}, provided \arg{flags} contains none of the {\tt CVT_*} flags. \cfunction{int}{PL_get_integer}{+term_t t, int *i} If \arg{t} is a Prolog integer, assign its value over \arg{i}. On 32-bit machines, this is the same as \cfuncref{PL_get_long}{}, but avoids a warning from the compiler. See also \cfuncref{PL_get_long}{} and \cfuncref{PL_get_integer_ex}{}. \cfunction{int}{PL_get_long}{term_t +t, long *i} If \arg{t} is a Prolog integer that can be represented as a long, assign its value over \arg{i}. If \arg{t} is an integer that cannot be represented by a C long, this function returns \const{FALSE}. If \arg{t} is a floating point number that can be represented as a long, this function succeeds as well. See also \cfuncref{PL_get_int64}{} and \cfuncref{PL_get_long_ex}{}. \cfunction{int}{PL_get_int64}{term_t +t, int64_t *i} If \arg{t} is a Prolog integer or float that can be represented as a \ctype{int64_t}, assign its value over \arg{i}. See also \cfuncref{PL_get_int64_ex}{}. \cfunction{int}{PL_get_uint64}{term_t +t, uint64_t *i} If \arg{t} is a Prolog integer that can be represented as a \ctype{uint64_t}, assign its value over \arg{i}. Note that this requires GMP support for representing \ctype{uint64_t} values with the high bit set. See also \cfuncref{PL_get_uint64_ex}{}. \cfunction{int}{PL_get_intptr}{term_t +t, intptr_t *i} Get an integer that is at least as wide as a pointer. On most platforms this is the same as \cfuncref{PL_get_long}{}, but on Win64 pointers are 8 bytes and longs only 4. Unlike \cfuncref{PL_get_pointer}{}, the value is not modified. \cfunction{int}{PL_get_bool}{term_t +t, int *val} If \arg{t} has the value \const{true}, \const{false}, set \arg{val} to the C constant \const{TRUE} or \const{FALSE} and return success, otherwise return failure. The values \const{on}, \const{1}, \const{off}, const{0} and are also accepted. \cfunction{int}{PL_get_pointer}{term_t +t, void **ptr} Together with \cfuncref{PL_put_pointer}{} and \cfuncref{PL_unify_pointer}{}, these functions allow representing a C pointer as a Prolog integer. The integer value is derived from the pointer, but not equivalent. The translation aims at producing smaller integers that fit more often in the \jargon{tagged} integer range. Representing C pointers as integers is \emph{unsafe}. The \jargon{blob} API described in \secref{blob} provides a safe way for handling foreign resources that cooperates with Prolog garbage collection. \cfunction{int}{PL_get_float}{term_t +t, double *f} If \arg{t} is a float, integer or rational number, its value is assigned over \arg{f}. Note that if \arg{t} is an integer or rational conversion may fail because the number cannot be represented as a float. \cfunction{int}{PL_get_functor}{term_t +t, functor_t *f} If \arg{t} is compound or an atom, the Prolog representation of the name-arity pair will be assigned over \arg{f}. See also \cfuncref{PL_get_name_arity}{} and \cfuncref{PL_is_functor}{}. \cfunction{int}{PL_get_name_arity}{term_t +t, atom_t *name, size_t *arity} If \arg{t} is compound or an atom, the functor name will be assigned over \arg{name} and the arity over \arg{arity} (either or both may be NULL). See also \cfuncref{PL_get_functor}{} and \cfuncref{PL_is_functor}{}. \cfunction{int}{PL_get_compound_name_arity}{term_t +t, atom_t *name, size_t *arity} If \arg{t} is compound term, the functor name will be assigned over \arg{name} and the arity over \arg{arity}. This is the same as \cfuncref{PL_get_name_arity}{}, but this function fails if \arg{t} is an atom. \cfunction{int}{PL_get_module}{term_t +t, module_t *module} If \arg{t} is an atom, the system will look up or create the corresponding module and assign an opaque pointer to it over {\em module}. \cfunction{int}{PL_get_arg}{size_t index, term_t +t, term_t -a} If \arg{t} is compound and index is between 1 and arity (inclusive), assign \arg{a} with a term reference to the argument. \cfunction{int}{_PL_get_arg}{size_t index, term_t +t, term_t -a} Same as \cfuncref{PL_get_arg}{}, but no checking is performed, neither whether \arg{t} is actually a term nor whether \arg{index} is a valid argument index. \cfunction{int}{PL_get_dict_key}{atom_t key, term_t +dict, term_t -value} If \arg{dict} is a dict, get the associated value in \arg{value}. Fails silently if \arg{key} does not appear in \arg{dict} or if if \arg{dict} is not a dict. \end{description} \subsubsection{Exchanging text using length and string} \label{sec:foreign-text-with-length} All internal text representation in SWI-Prolog is represented using \type{char *} plus length and allow for \jargon{0-bytes} in them. The foreign library supports this by implementing a *_nchars() function for each applicable *_chars() function. Below we briefly present the signatures of these functions. For full documentation consult the *_chars() function. \begin{description} \cfunction{int}{PL_get_atom_nchars}{term_t t, size_t *len, char **s} See \cfuncref{PL_get_atom_chars}{}. \cfunction{int}{PL_get_list_nchars}{term_t t, size_t *len, char **s} See \cfuncref{PL_get_list_chars}{}. \cfunction{int}{PL_get_nchars}{term_t t, size_t *len, char **s, unsigned int flags} See \cfuncref{PL_get_chars}{}. The \arg{len} pointer may be \const{NULL}. \cfunction{int}{PL_put_atom_nchars}{term_t t, size_t len, const char *s} See \cfuncref{PL_put_atom_chars}{}. \cfunction{int}{PL_put_string_nchars}{term_t t, size_t len, const char *s} See \cfuncref{PL_put_string_chars}{}. \cfunction{int}{PL_put_list_ncodes}{term_t t, size_t len, const char *s} See \cfuncref{PL_put_list_codes}{}. \cfunction{int}{PL_put_list_nchars}{term_t t, size_t len, const char *s} See \cfuncref{PL_put_list_chars}{}. \cfunction{int}{PL_unify_atom_nchars}{term_t t, size_t len, const char *s} See \cfuncref{PL_unify_atom_chars}{}. \cfunction{int}{PL_unify_string_nchars}{term_t t, size_t len, const char *s} See \cfuncref{PL_unify_string_chars}{}. \cfunction{int}{PL_unify_list_ncodes}{term_t t, size_t len, const char *s} See \cfuncref{PL_unify_codes}{}. \cfunction{int}{PL_unify_list_nchars}{term_t t, size_t len, const char *s} See \cfuncref{PL_unify_list_chars}{}. \end{description} In addition, the following functions are available for creating and inspecting atoms: \begin{description} \cfunction{atom_t}{PL_new_atom_nchars}{size_t len, const char *s} Create a new atom as \cfuncref{PL_new_atom}{}, but using the given length and characters. If \arg{len} is \exam{(size_t)-1}, it is computed from \arg{s} using strlen(). See \cfuncref{PL_new_atom}{} for error handling. \cfunction{const char *}{PL_atom_nchars}{atom_t a, size_t *len} Extract the text and length of an atom. If you do not need the length, pass NULL as the value of \arg{len}. If \cfuncref{PL_atom_nchars}{} is called for a blob, NULL is returned. \end{description} \subsubsection{Wide-character versions} \label{sec:foreign-unicode} Support for exchange of wide-character strings is still under consideration. The functions dealing with 8-bit character strings return failure when operating on a wide-character atom or Prolog string object. The functions below can extract and unify both 8-bit and wide atoms and string objects. Wide character strings are represented as C arrays of objects of the type \ctype{pl_wchar_t}, which is guaranteed to be the same as \ctype{wchar_t} on platforms supporting this type. For example, on MS-Windows, this represents a 16-bit UTF-16 string, while using the GNU C library (glibc) this represents 32-bit UCS4 characters. \begin{description} \cfunction{atom_t}{PL_new_atom_wchars}{size_t len, const pl_wchar_t *s} Create atom from wide-character string as \cfuncref{PL_new_atom_nchars}{} does for ISO-Latin-1 strings. If \arg{s} only contains ISO-Latin-1 characters a normal byte-array atom is created. If \arg{len} is \exam{(size_t)-1}, it is computed from \arg{s} using wcslen(). See \cfuncref{PL_new_atom}{} for error handling. \cfunction{const pl_wchar_t*}{PL_atom_wchars}{atom_t atom, size_t *len} Extract characters from a wide-character atom. Succeeds on any atom marked as `text'. If the underlying atom is a wide-character atom, the returned pointer is a pointer into the atom structure. If the atom is represented as an ISO-Latin-1 string, the returned pointer comes from Prolog's `buffer stack' (see \secref{foreign-strings}). \cfunction{int}{PL_get_wchars}{term_t t, size_t *len, pl_wchar_t **s, unsigned flags} Wide-character version of \cfuncref{PL_get_chars}{}. The \arg{flags} argument is the same as for \cfuncref{PL_get_chars}{}. Note that this operation may return a pointer into Prolog's `buffer stack' (see \secref{foreign-strings}). \cfunction{int}{PL_put_wchars}{term_t -t, int type, size_t len, const pl_wchar_t *s} \textit{Put} text from a wide character array in \arg{t}. Arguments are the same as \cfuncref{PL_unify_wchars}{}.\footnote{The current implemention uses \cfuncref{PL_put_variable}{} followed by \cfuncref{PL_unify_wchars}{}.} \cfunction{int}{PL_unify_wchars}{term_t +t, int type, size_t len, const pl_wchar_t *s} Unify \arg{t} with a textual representation of the C wide-character array \arg{s}. The \arg{type} argument defines the Prolog representation and is one of \const{PL_ATOM}, \const{PL_STRING}, \const{PL_CODE_LIST} or \const{PL_CHAR_LIST}. \cfunction{int}{PL_unify_wchars_diff}{term_t +t, term_t -tail, int type, size_t len, const pl_wchar_t *s} Difference list version of \cfuncref{PL_unify_wchars}{}, only supporting the types \const{PL_CODE_LIST} and \const{PL_CHAR_LIST}. It serves two purposes. It allows for returning very long lists from data read from a stream without the need for a resizing buffer in C. Also, the use of difference lists is often practical for further processing in Prolog. Examples can be found in \file{packages/clib/readutil.c} from the source distribution. \end{description} \subsubsection{Reading a list} \label{sec:foreign-read-list} The functions from this section are intended to read a Prolog list from C. Suppose we expect a list of atoms; the code below will print the atoms, each on a line. Please note the following: \begin{itemize} \item We need a \ctype{term_t} \jargon{term reference} for the elements (\arg{head}). This reference is reused for each element. \item We walk over the list using \cfuncref{PL_get_list_ex}{} which overwrites the list \ctype{term_t}. As it is not allowed to overwrite the \ctype{term_t} passed in as arguments to a predicate, we must \emph{copy} the argument \ctype{term_t}. \item SWI-Prolog atoms are Unicode objects. The \cfuncref{PL_get_chars}{} returns a \ctype{char*}. We want it to convert atoms, return the result as a \jargon{multibyte} string (\const{REP_UTF8} may also be used) and finally we want an exception on type, instantiation or representation errors (if the system's default encoding cannot represent some characters of the Unicode atom). This may create temporary copies of the atom text - \cfuncref{PL_STRINGS_MARK}{} $\ldots$ \cfuncref{PL_STRINGS_RELEASE}{} handles that. \item The *_ex() API functions are functionally the same as the ones without the \const{_ex} suffix, but they raise type, domain, or instantiation errors when the input is invalid; whereas the plain version may only raise resource exceptions if the request cannot be fullfilled due to resource exhaustion. \item \cfuncref{PL_get_nil_ex}{} is designed to propagate an already raised exception. \end{itemize} \begin{code} foreign_t pl_write_atoms(term_t l) { term_t head = PL_new_term_ref(); /* the elements */ term_t tail = PL_copy_term_ref(l); /* copy (we modify tail) */ int rc = TRUE; while( rc && PL_get_list_ex(tail, head, tail) ) { PL_STRINGS_MARK(); char *s; if (rc=PL_get_chars(head, &s, CVT_ATOM|REP_MB|CVT_EXCEPTION)) ) Sprintf("%s\n", s); PL_STRINGS_RELEASE(); } return rc && PL_get_nil_ex(tail); /* test end for [] */ } \end{code} \noindent Note that as of version~7, lists have a new representation unless the option \cmdlineoption{--traditional} is used. see \secref{ext-lists}. \begin{description} \cfunction{int}{PL_get_list}{term_t +l, term_t -h, term_t -t} If \arg{l} is a list and not the empty list, assign a term reference to the head to \arg{h} and to the tail to \arg{t}. \cfunction{int}{PL_get_head}{term_t +l, term_t -h} If \arg{l} is a list and not the empty list, assign a term reference to the head to \arg{h}. \cfunction{int}{PL_get_tail}{term_t +l, term_t -t} If \arg{l} is a list and not the empty list, assign a term reference to the tail to \arg{t}. \cfunction{int}{PL_get_nil}{term_t +l} Succeeds if \arg{l} represents the list termination constant. \cfunction{int}{PL_skip_list}{term_t +list, term_t -tail, size_t *len} This is a multi-purpose function to deal with lists. It allows for finding the length of a list, checking whether something is a list, etc. The reference \arg{tail} is set to point to the end of the list, \arg{len} is filled with the number of list-cells skipped, and the return value indicates the status of the list: \begin{description} \constitem{PL_LIST} The list is a `proper' list: one that ends in the list terminator constant and \arg{tail} is filled with the terminator constant. \constitem{PL_PARTIAL_LIST} The list is a `partial' list: one that ends in a variable and \arg{tail} is a reference to this variable. \constitem{PL_CYCLIC_TERM} The list is cyclic (e.g. X = [a|X]). \arg{tail} points to an arbitrary cell of the list and \arg{len} is at most twice the cycle length of the list. \constitem{PL_NOT_A_LIST} The term \arg{list} is not a list at all. \arg{tail} is bound to the non-list term and \arg{len} is set to the number of list-cells skipped. \end{description} It is allowed to pass 0 for \arg{tail} and \const{NULL} for \arg{len}. \end{description} \subsubsection{Processing option lists and dicts} \label{sec:foreign-options} \begin{description} \cfunction{int}{PL_scan_options}{term_t options, int flags, const char* opttype, PL_option_t specs[], ...} Process an \jargon{option list} as we find with, e.g., \index{write_term/2}\predref{write_term}{2} and many other builtin predicates. This function takes an option list (or dict) and in the variadic argument list pointers that receive the option values. \cfuncref{PL_scan_options}{} takes care of validating the list, ensuring the list is not cyclic, validating the option type and storing the converted values using the supplied pointers. Below is an example. While \ctype{PL_option_t} is a struct, its members are initialised using the \cfuncref{PL_OPTION}{} macro. The data structure is not constant because \cfuncref{PL_scan_options}{} adds the option names as \jargon{atoms} to speed up option processing. The macro PL_OPTIONS_END terminates the option list. \begin{code} static PL_option_t mypred_options[] = { PL_OPTION("quoted", OPT_BOOL), PL_OPTION("length", OPT_SIZE), PL_OPTION("callback", OPT_TERM), PL_OPTIONS_END }; static foreign_t mypred(term_t a1, term_t options) { int quoted = FALSE; size_t length = 10; term_t callback = 0; if ( !PL_scan_options(options, 0, "mypred_options", mypred_options, "ed, &length, &callback) ) return FALSE; } \end{code} \noindent The only defined value for \arg{flags} is currently \const{OPT_ALL}, which causes this function to raise a domain error if an option is passed that is not in \arg{specs}. Default in SWI-Prolog is to silently ignore unknown options, unless the Prolog flag \prologflag{iso} is \const{true}. The \arg{opttype} argument defines the type (group) of the options, e.g., \exam{"write_option"}. Option \jargon{types} are defined by the ISO standard. SWI-Prolog only uses this if \const{OPT_ALL} is specified, to raise a \const{domain_error} of the indicated type if some option is unused. The type name is normally the name of the predicate followed by \const{_option} or the name of a representative of a group of predicates to which the options apply. Defined option types and their corresponding pointer type are described below. \begin{description} \definition{\const{OPT_BOOL} \ctype{int}} Convert the option value to a bool. This converts the values described by \cfuncref{PL_get_bool}{}. In addition, an option without a value (i.e., a plain atom that denotes the option name) can act as a boolean \const{TRUE}. \definition{\const{OPT_INT} \ctype{int}} \nodescription \definition{\const{OPT_INT64} \ctype{int64_t}} \nodescription \definition{\const{OPT_UINT64} \ctype{uint64_t}} \nodescription \definition{\const{OPT_SIZE} \ctype{size_t}} \nodescription \definition{\const{OPT_DOUBLE} \ctype{double}} Numeric values of various types. Raises an error if the Prolog value cannot be represented by the C type. \definition{\const{OPT_STRING} \ctype{char*}} Uses \cfuncref{PL_get_chars}{} using the flags \const{CVT_ALL|REP_UTF8|BUF_STACK|CVT_EXCEPTION}. The buffered string must be guarded using \cfuncref{PL_STRINGS_MARK}{} and \cfuncref{PL_STRINGS_RELEASE}{}. \definition{\const{OPT_ATOM} \ctype{atom_t}} Accepts an atom. Note that if the C function that implements the predicate wishes to keep hold of the atom after it returns it must use \cfuncref{PL_register_atom}{}. \definition{\const{OPT_TERM} \ctype{term_t}} Accepts an arbitrary Prolog term. The term handle is scoped by the foreign predicate invocation. Terms can be preserved using \cfuncref{PL_record}{}. \end{description} The ISO standard demands that if an option is repeated the \emph{last} occurance holds. This implies that \cfuncref{PL_scan_options}{} must scan the option list to the end. \end{description} \subsubsection{An example: defining \index{write/1}\predref{write}{1} in C} \label{sec:foreign-write} \Figref{pl-display} shows a simplified definition of \index{write/1}\predref{write}{1} to illustrate the described functions. This simplified version does not deal with operators. It is called \index{display/1}\predref{display}{1}, because it mimics closely the behaviour of this Edinburgh predicate. \begin{figure} \begin{code} foreign_t pl_display(term_t t) { functor_t functor; int arity, len, n; char *s; switch( PL_term_type(t) ) { case PL_VARIABLE: case PL_ATOM: case PL_INTEGER: case PL_FLOAT: PL_get_chars(t, &s, CVT_ALL); Sprintf("%s", s); break; case PL_STRING: PL_get_string_chars(t, &s, &len); Sprintf("\"%s\"", s); break; case PL_TERM: { term_t a = PL_new_term_ref(); PL_get_name_arity(t, &name, &arity); Sprintf("%s(", PL_atom_chars(name)); for(n=1; n<=arity; n++) { PL_get_arg(n, t, a); if ( n > 1 ) Sprintf(", "); pl_display(a); } Sprintf(")"); break; default: PL_fail; /* should not happen */ } } PL_succeed; } \end{code} \noindent \caption{A Foreign definition of \index{display/1}\predref{display}{1}} \label{fig:pl-display} \end{figure} \subsection{Constructing Terms} \label{sec:foreign-term-construct} Terms can be constructed using functions from the {\tt PL_put_*()} and {\tt PL_cons_*()} families. This approach builds the term `inside-out', starting at the leaves and subsequently creating compound terms. Alternatively, terms may be created `top-down', first creating a compound holding only variables and subsequently unifying the arguments. This section discusses functions for the first approach. This approach is generally used for creating arguments for \cfuncref{PL_call}{} and \cfuncref{PL_open_query}{}. \begin{description} \cfunction{int}{PL_put_variable}{term_t -t} Put a fresh variable in the term, resetting the term reference to its initial state.\footnote{Older versions created a variable on the global stack.} \cfunction{int}{PL_put_atom}{term_t -t, atom_t a} Put an atom in the term reference from a handle. See also \cfuncref{PL_new_atom}{} and \cfuncref{PL_atom_chars}{}. \cfunction{int}{PL_put_bool}{term_t -t, int val} Put one of the atoms \const{true} or \const{false} in the term reference See also \cfuncref{PL_put_atom}{}, \cfuncref{PL_unify_bool}{} and \cfuncref{PL_get_bool}{}. \cfunction{int}{PL_put_chars}{term_t -t, int flags, size_t len, const char *chars} New function to deal with setting a term from a \ctype{char*} with various encodings. The \arg{flags} argument is a bitwise \emph{or} specifying the Prolog target type and the encoding of \arg{chars}. A Prolog type is one of \const{PL_ATOM}, \const{PL_STRING}, \const{PL_CODE_LIST} or \const{PL_CHAR_LIST}. A representation is one of \const{REP_ISO_LATIN_1}, \const{REP_UTF8} or \const{REP_MB}. See \cfuncref{PL_get_chars}{} for a definition of the representation types. If \arg{len} is \const{-1} \arg{chars} must be zero-terminated and the length is computed from \arg{chars} using strlen(). \cfunction{int}{PL_put_atom_chars}{term_t -t, const char *chars} Put an atom in the term reference constructed from the zero-terminated string. The string itself will never be referenced by Prolog after this function. \cfunction{int}{PL_put_string_chars}{term_t -t, const char *chars} Put a zero-terminated string in the term reference. The data will be copied. See also \cfuncref{PL_put_string_nchars}{}. \cfunction{int}{PL_put_string_nchars}{term_t -t, size_t len, const char *chars} Put a string, represented by a length/start pointer pair in the term reference. The data will be copied. This interface can deal with 0-bytes in the string. See also \secref{foreigndata}. \cfunction{int}{PL_put_list_chars}{term_t -t, const char *chars} Put a list of ASCII values in the term reference. \cfunction{int}{PL_put_integer}{term_t -t, long i} Put a Prolog integer in the term reference. \cfunction{int}{PL_put_int64}{term_t -t, int64_t i} Put a Prolog integer in the term reference. \cfunction{int}{PL_put_uint64}{term_t -t, uint64_t i} Put a Prolog integer in the term reference. Note that unbounded integer support is required for \ctype{uint64_t} values with the highest bit set to 1. Without unbounded integer support, too large values raise a \const{representation_error} exception. \cfunction{int}{PL_put_pointer}{term_t -t, void *ptr} Put a Prolog integer in the term reference. Provided \arg{ptr} is in the `malloc()-area', \cfuncref{PL_get_pointer}{} will get the pointer back. \cfunction{int}{PL_put_float}{term_t -t, double f} Put a floating-point value in the term reference. \cfunction{int}{PL_put_functor}{term_t -t, functor_t functor} Create a new compound term from \arg{functor} and bind \arg{t} to this term. All arguments of the term will be variables. To create a term with instantiated arguments, either instantiate the arguments using the {\tt PL_unify_*()} functions or use \cfuncref{PL_cons_functor}{}. \cfunction{int}{PL_put_list}{term_t -l} As \cfuncref{PL_put_functor}{}, using the list-cell functor. Note that on classical Prolog systems or in SWI-Prolog using the option \cmdlineoption{--traditional}, this is \functor{\Sdot}{2}, while on SWI-Prolog version~7 this is \functor{\Scons}{2}. \cfunction{int}{PL_put_nil}{term_t -l} Put the list terminator constant in \arg{l}. Always returns \const{TRUE}. Note that in classical Prolog systems or in SWI-Prolog using the option \cmdlineoption{--traditional}, this is the same as \exam{\cfuncref{PL_put_atom_chars}{"[]"}}. See \secref{ext-lists}. \cfunction{int}{PL_put_term}{term_t -t1, term_t +t2} Make \arg{t1} point to the same term as \arg{t2}. Under the unusual condition that \arg{t2} is a fresh term reference this function requires a global stack cell and may thus return \arg{FALSE} and leave a resource exception in the environment. \cfunction{int}{PL_cons_functor}{term_t -h, functor_t f, \ldots} Create a term whose arguments are filled from a variable argument list holding the same number of \ctype{term_t} objects as the arity of the functor. To create the term \exam{animal(gnu, 50)}, use: \begin{code} { term_t a1 = PL_new_term_ref(); term_t a2 = PL_new_term_ref(); term_t t = PL_new_term_ref(); functor_t animal2; /* animal2 is a constant that may be bound to a global variable and re-used */ animal2 = PL_new_functor(PL_new_atom("animal"), 2); PL_put_atom_chars(a1, "gnu"); PL_put_integer(a2, 50); PL_cons_functor(t, animal2, a1, a2); } \end{code} \noindent After this sequence, the term references \arg{a1} and \arg{a2} may be used for other purposes. \cfunction{int}{PL_cons_functor_v}{term_t -h, functor_t f, term_t a0} Create a compound term like \cfuncref{PL_cons_functor}{}, but \arg{a0} is an array of term references as returned by \cfuncref{PL_new_term_refs}{}. The length of this array should match the number of arguments required by the functor. \cfunction{int}{PL_cons_list}{term_t -l, term_t +h, term_t +t} Create a list (cons-) cell in \arg{l} from the head \arg{h} and tail \arg{t}. As with \cfuncref{PL_cons_functor}{}, the term references \arg{h} and \arg{t} may be used for other purposes after the call to \cfuncref{PL_cons_list}{}. The code below creates a list of atoms from a \ctype{char **}. The list is built tail-to-head. The {\tt PL_unify_*()} functions can be used instead to build a list head-to-tail. \begin{code} void put_list(term_t l, int n, char **words) { term_t a = PL_new_term_ref(); PL_put_nil(l); while( --n >= 0 ) { PL_put_atom_chars(a, words[n]); PL_cons_list(l, a, l); } } \end{code} \noindent \cfunction{int}{PL_put_dict}{term_t -h, atom_t tag, size_t len, const atom_t *keys, term_t values} Create a dict from a \arg{tag} and vector of atom-value pairs and put the result in \arg{h}. The dict's key is set by \arg{tag}, which may be \const{0} to leave the tag unbound. The \arg{keys} vector is a vector of atoms of at least \arg{len} long. The \arg{values} is a term vector allocated using \cfuncref{PL_new_term_refs}{} of at least \arg{len} long. This function returns \const{TRUE} on success, \const{FALSE} on a resource error (leaving a resource error exception in the environment), \const{-1} if some key or the \arg{tag} is invalid and \const{-2} if there are duplicate keys. \end{description} \subsection{Unifying data} \label{sec:foreign-unify} The functions of this section \jargon{unify} terms with other terms or translated C data structures. Except for \cfuncref{PL_unify}{}, these functions are specific to SWI-Prolog. They have been introduced because they shorten the code for returning data to Prolog and at the same time make this more efficient by avoiding the need to allocate temporary term references and reduce the number of calls to the Prolog API. Consider the case where we want a foreign function to return the host name of the machine Prolog is running on. Using the {\tt PL_get_*()} and {\tt PL_put_*()} functions, the code becomes: \begin{code} foreign_t pl_hostname(term_t name) { char buf[100]; if ( gethostname(buf, sizeof buf) ) { term_t tmp = PL_new_term_ref(); PL_put_atom_chars(tmp, buf); return PL_unify(name, tmp); } PL_fail; } \end{code} \noindent Using \cfuncref{PL_unify_atom_chars}{}, this becomes: \begin{code} foreign_t pl_hostname(term_t name) { char buf[100]; if ( gethostname(buf, sizeof buf) ) return PL_unify_atom_chars(name, buf); PL_fail; } \end{code} \noindent Note that unification functions that perform multiple bindings may leave part of the bindings in case of failure. See \cfuncref{PL_unify}{} for details. \begin{description} \cfunction{int}{PL_unify}{term_t ?t1, term_t ?t2} Unify two Prolog terms and return \const{TRUE} on success. \cfuncref{PL_unify}{} does not evaluate \jargon{attributed variables} (see \secref{attvar}), it merely schedules the goals associated with the attributes to be executed \emph{after} the foreign predicate succeeds.\footnote{Goal associated with attributes may be non-deterministic, which we cannot handle from a callback. A callback could also result in deeply nested mutual recursion between C and Prolog and eventually trigger a C stack overflow.} Care is needed if \cfuncref{PL_unify}{} returns \const{FALSE} and the foreign function does not \emph{immediately} return to Prolog with \const{FALSE}. Unification may perform multiple changes to either \arg{t1} or \arg{t2}. A failing unification may have created bindings before failure is detected. \emph{Already created bindings are not undone}. For example, calling \cfuncref{PL_unify}{} on \term{a}{X, a} and \term{a}{c,b} binds \arg{X} to \const{c} and fails when trying to unify \const{a} to \const{b}. If control remains in C or even if we want to return success to Prolog, we \emph{must} undo such bindings. In addition, \cfuncref{PL_unify}{} may have failed on an \textbf{exception}, typically a resource (stack) overflow. This can be tested using \cfuncref{PL_exception}{}, passing 0 (zero) for the query-id argument. Foreign functions that encounter an exception must return \const{FALSE} to Prolog as soon as possible or call \cfuncref{PL_clear_exception}{} if they wish to ignore the exception. Note that there can only be an exception if \cfuncref{PL_unify}{} returned \const{FALSE}. This is achieved using \cfuncref{PL_open_foreign_frame}{} and \cfuncref{PL_rewind_foreign_frame}{}, as shown in the snippet below. \begin{code} { fid_t fid = PL_open_foreign_frame(); ... if ( !PL_unify(t1, t2) ) { if ( PL_exception(0) ) { PL_close_foreign_frame(fid); return FALSE; } PL_rewind_foreign_frame(fid); } ... PL_close_foreign_frame(fid); } \end{code} \noindent This code is only needed if the foreign predicate does not return immediately to Prolog when \cfuncref{PL_unify}{} fails - there is an implicit frame around the entire predicate, and returning \const{FALSE} undoes all bindings when that frame is closed. \cfunction{int}{PL_unify_atom}{term_t ?t, atom_t a} Unify \arg{t} with the atom \arg{a} and return non-zero on success. \cfunction{int}{PL_unify_bool}{term_t ?t, int a} Unify \arg{t} with either \const{false} or \const{true}, according to whether \arg{a} is zero or non-zero. If \arg{t} is instantiated, \const{off} and \const{on} are also accepted. \cfunction{int}{PL_unify_chars}{term_t ?t, int flags, size_t len, const char *chars} New function to deal with unification of \ctype{char*} with various encodings to a Prolog representation. The \arg{flags} argument is a bitwise \emph{or} specifying the Prolog target type and the encoding of \arg{chars}. A Prolog type is one of \const{PL_ATOM}, \const{PL_STRING}, \const{PL_CODE_LIST} or \const{PL_CHAR_LIST}. A representation is one of \const{REP_ISO_LATIN_1}, \const{REP_UTF8} or \const{REP_MB}. See \cfuncref{PL_get_chars}{} for a definition of the representation types. If \arg{len} is \const{-1} \arg{chars} must be zero-terminated and the length is computed from \arg{chars} using strlen(). If \arg{flags} includes \const{PL_DIFF_LIST} and type is one of \const{PL_CODE_LIST} or \const{PL_CHAR_LIST}, the text is converted to a \jargon{difference list}. The tail of the difference list is $t+1$. \cfunction{int}{PL_unify_atom_chars}{term_t ?t, const char *chars} Unify \arg{t} with an atom created from \arg{chars} and return non-zero on success. \cfunction{int}{PL_unify_list_chars}{term_t ?t, const char *chars} Unify \arg{t} with a list of ASCII characters constructed from \arg{chars}. \cfunction{void}{PL_unify_string_chars}{term_t ?t, const char *chars} Unify \arg{t} with a Prolog string object created from the zero-terminated string \arg{chars}. The data will be copied. See also \cfuncref{PL_unify_string_nchars}{}. \cfunction{int}{PL_unify_integer}{term_t ?t, intptr_t n} Unify \arg{t} with a Prolog integer from \arg{n}. \cfunction{int}{PL_unify_int64}{term_t ?t, int64_t n} Unify \arg{t} with a Prolog integer from \arg{n}. \cfunction{int}{PL_unify_uint64}{term_t ?t, uint64_t n} Unify \arg{t} with a Prolog integer from \arg{n}. Note that unbounded integer support is required if \arg{n} does not fit in a \emph{signed} \ctype{int64_t}. If unbounded integers are not supported a \const{representation_error} is raised. \cfunction{int}{PL_unify_float}{term_t ?t, double f} Unify \arg{t} with a Prolog float from \arg{f}. \cfunction{int}{PL_unify_pointer}{term_t ?t, void *ptr} Unify \arg{t} with a Prolog integer describing the pointer. See also \cfuncref{PL_put_pointer}{} and \cfuncref{PL_get_pointer}{}. \cfunction{int}{PL_unify_functor}{term_t ?t, functor_t f} If \arg{t} is a compound term with the given functor, just succeed. If it is unbound, create a term and bind the variable, else fail. Note that this function does not create a term if the argument is already instantiated. If \arg{f} is a functor with arity 0, \arg{t} is unified with an atom. See also \cfuncref{PL_unify_compound}{}. \cfunction{int}{PL_unify_compound}{term_t ?t, functor_t f} If \arg{t} is a compound term with the given functor, just succeed. If it is unbound, create a term and bind the variable, else fail. Note that this function does not create a term if the argument is already instantiated. If \arg{f} is a functor with arity 0, \arg{t} is unified with compound without arguments. See also \cfuncref{PL_unify_functor}{}. \cfunction{int}{PL_unify_list}{term_t ?l, term_t -h, term_t -t} Unify \arg{l} with a list-cell ({\tt ./2}). If successful, write a reference to the head of the list into \arg{h} and a reference to the tail of the list into \arg{t}. This reference to \arg{h} may be used for subsequent calls to this function. Suppose we want to return a list of atoms from a \ctype{char **}. We could use the example described by \cfuncref{PL_cons_list}{}, followed by a call to \cfuncref{PL_unify}{}, or we can use the code below. If the predicate argument is unbound, the difference is minimal (the code based on \cfuncref{PL_cons_list}{} is probably slightly faster). If the argument is bound, the code below may fail before reaching the end of the word list, but even if the unification succeeds, this code avoids a duplicate (garbage) list and a deep unification. Note that \cfuncref{PL_unify_list}{} is not used with \arg{env} but with \exam{tail}, which is a copy of \arg{env}. \cfuncref{PL_copy_term_ref}{} creates a copy \ctype{term_t} holding the same Prolog term, i.e., \emph{not} a copy of the Prolog term. The only thing that is allowed to be done with an argument to a foreign predicate (such as \arg{env}) is unification; for anything that might over-write the term, you must use a copy created by \cfuncref{PL_copy_term_ref}{}. The name \cfuncref{PL_unify_list}{} is slightly misleading - it unifies the first argumment (\arg{l} but \emph{overwrites} the second (\arg{h}) and third (\arg{t}) arguments. \begin{code} foreign_t pl_get_environ(term_t env) { term_t tail = PL_copy_term_ref(env); term_t item = PL_new_term_ref(); extern char **environ; for(const char **e = environ; *e; e++) { if ( !PL_unify_list(tail, item, tail) || !PL_unify_atom_chars(item, *e) ) PL_fail; } return PL_unify_nil(tail); } \end{code} \noindent In this example, \exam{item} is initialized outside the loop. This allocates a single new reference to a term, which is used as a temporary inside the loop - there is no need to allocate a new reference each time around the loop because the \exam{item} term reference can be reused and the call to \cfuncref{PL_unify_list}{} copies a reference to the new list cell's head into the the term referenced by \exam{item}. \cfunction{int}{PL_unify_nil}{term_t ?l} Unify \arg{l} with the atom \const{\Snil}. \cfunction{int}{PL_unify_arg}{int index, term_t ?t, term_t ?a} Unifies the {\em index-th} argument (1-based) of \arg{t} with \arg{a}. \cfunction{int}{PL_unify_term}{term_t ?t, \ldots} Unify \arg{t} with a (normally) compound term. The remaining arguments are a sequence of a type identifier followed by the required arguments. This predicate is an extension to the Quintus and SICStus foreign interface from which the SWI-Prolog foreign interface has been derived, but has proved to be a powerful and comfortable way to create compound terms from C. Due to the vararg packing/unpacking and the required type-switching this interface is slightly slower than using the primitives. Please note that some bad C compilers have fairly low limits on the number of arguments that may be passed to a function. Special attention is required when passing numbers. C `promotes' any integral smaller than \type{int} to \type{int}. That is, the types \type{char}, \type{short} and \type{int} are all passed as \type{int}. In addition, on most 32-bit platforms \type{int} and \type{long} are the same. Up to version 4.0.5, only \const{PL_INTEGER} could be specified, which was taken from the stack as \type{long}. Such code fails when passing small integral types on machines where \type{int} is smaller than \type{long}. It is advised to use \const{PL_SHORT}, \const{PL_INT} or \const{PL_LONG} as appropriate. Similarly, C compilers promote \type{float} to \type{double} and therefore \const{PL_FLOAT} and \const{PL_DOUBLE} are synonyms. The type identifiers are: \begin{description} \definition{\const{PL_VARIABLE} \arg{none}} No op. Used in arguments of \const{PL_FUNCTOR}. \definition{\const{PL_BOOL} \arg{int}} Unify the argument with \const{true} or \const{false}. \definition{\const{PL_ATOM} \arg{atom_t}} Unify the argument with an atom, as in \cfuncref{PL_unify_atom}{}. \definition{\const{PL_CHARS} \arg{const char *}} Unify the argument with an atom constructed from the C \ctype{char *}, as in \cfuncref{PL_unify_atom_chars}{}. \definition{\const{PL_NCHARS} \arg{size_t, const char *}} Unify the argument with an atom constructed from length and \ctype{char*} as in \cfuncref{PL_unify_atom_nchars}{}. \definition{\const{PL_UTF8_CHARS} \arg{const char *}} Create an atom from a UTF-8 string. \definition{\const{PL_UTF8_STRING} \arg{const char *}} Create a packed string object from a UTF-8 string. \definition{\const{PL_MBCHARS} \arg{const char *}} Create an atom from a multi-byte string in the current locale. \definition{\const{PL_MBCODES} \arg{const char *}} Create a list of character codes from a multi-byte string in the current locale. \definition{\const{PL_MBSTRING} \arg{const char *}} Create a packed string object from a multi-byte string in the current locale. \definition{\const{PL_NWCHARS} \arg{size_t, const wchar_t *}} Create an atom from a length and a wide character pointer. \definition{\const{PL_NWCODES} \arg{size_t, const wchar_t *}} Create a list of character codes from a length and a wide character pointer. \definition{\const{PL_NWSTRING} \arg{size_t, const wchar_t *}} Create a packed string object from a length and a wide character pointer. \definition{\const{PL_SHORT} \arg{short}} Unify the argument with an integer, as in \cfuncref{PL_unify_integer}{}. As \type{short} is promoted to \type{int}, \const{PL_SHORT} is a synonym for \type{PL_INT}. \definition{\const{PL_INTEGER} \arg{long}} Unify the argument with an integer, as in \cfuncref{PL_unify_integer}{}. \definition{\const{PL_INT} \arg{int}} Unify the argument with an integer, as in \cfuncref{PL_unify_integer}{}. \definition{\const{PL_LONG} \arg{long}} Unify the argument with an integer, as in \cfuncref{PL_unify_integer}{}. \definition{\const{PL_INT64} \arg{int64_t}} Unify the argument with a 64-bit integer, as in \cfuncref{PL_unify_int64}{}. \definition{\const{PL_INTPTR} \arg{intptr_t}} Unify the argument with an integer with the same width as a pointer. On most machines this is the same as \const{PL_LONG}. but on 64-bit MS-Windows pointers are 64 bits while longs are only 32 bits. \definition{\const{PL_DOUBLE} \arg{double}} Unify the argument with a float, as in \cfuncref{PL_unify_float}{}. Note that, as the argument is passed using the C vararg conventions, a float must be casted to a double explicitly. \definition{\const{PL_FLOAT} \arg{double}} Unify the argument with a float, as in \cfuncref{PL_unify_float}{}. \definition{\const{PL_POINTER} \arg{void *}} Unify the argument with a pointer, as in \cfuncref{PL_unify_pointer}{}. \definition{\const{PL_STRING} \arg{const char *}} Unify the argument with a string object, as in \cfuncref{PL_unify_string_chars}{}. \definition{\const{PL_TERM} \arg{term_t}} Unify a subterm. Note this may be the return value of a \cfuncref{PL_new_term_ref}{} call to get access to a variable. \definition{\const{PL_FUNCTOR} \arg{functor_t, \ldots}} Unify the argument with a compound term. This specification should be followed by exactly as many specifications as the number of arguments of the compound term. \definition{\const{PL_FUNCTOR_CHARS} \arg{const char *name, int arity, \ldots}} Create a functor from the given name and arity and then behave as \const{PL_FUNCTOR}. \definition{\const{PL_LIST} \arg{int length, \ldots}} Create a list of the indicated length. The remaining arguments contain the elements of the list. \end{description} For example, to unify an argument with the term \exam{language(dutch)}, the following skeleton may be used: \begin{code} static functor_t FUNCTOR_language1; static void init_constants() { FUNCTOR_language1 = PL_new_functor(PL_new_atom("language"),1); } foreign_t pl_get_lang(term_t r) { return PL_unify_term(r, PL_FUNCTOR, FUNCTOR_language1, PL_CHARS, "dutch"); } install_t install() { PL_register_foreign("get_lang", 1, pl_get_lang, 0); init_constants(); } \end{code} \noindent \cfunction{int}{PL_chars_to_term}{const char *chars, term_t -t} Parse the string \arg{chars} and put the resulting Prolog term into \arg{t}. \arg{chars} may or may not be closed using a Prolog full-stop (i.e., a dot followed by a blank). Returns \const{FALSE} if a syntax error was encountered and \const{TRUE} after successful completion. In addition to returning \const{FALSE}, the exception-term is returned in \arg{t} on a syntax error. See also \index{term_to_atom/2}\predref{term_to_atom}{2}. The following example builds a goal term from a string and calls it. \begin{code} int call_chars(const char *goal) { fid_t fid = PL_open_foreign_frame(); term_t g = PL_new_term_ref(); BOOL rval; if ( PL_chars_to_term(goal, g) ) rval = PL_call(goal, NULL); else rval = FALSE; PL_discard_foreign_frame(fid); return rval; } ... call_chars("consult(load)"); ... \end{code} \noindent \cfuncref{PL_chars_to_term}{} is defined using \cfuncref{PL_put_term_from_chars}{} which can deal with not null-terminated strings as well as strings using different encodings: \begin{code} int PL_chars_to_term(const char *s, term_t t) { return PL_put_term_from_chars(t, REP_ISO_LATIN_1, (size_t)-1, s); } \end{code} \noindent \cfunction{int}{PL_wchars_to_term}{const pl_wchar_t *chars, term_t -t} Wide character version of \cfuncref{PL_chars_to_term}{}. \cfunction{char *}{PL_quote}{int chr, const char *string} Return a quoted version of \arg{string}. If \arg{chr} is \verb$'\''$, the result is a quoted atom. If \arg{chr} is \verb$'"'$, the result is a string. The result string is stored in the same ring of buffers as described with the \const{BUF_STACK} argument of \cfuncref{PL_get_chars}{}; In the current implementation, the string is surrounded by \arg{chr} and any occurrence of \arg{chr} is doubled. In the future the behaviour will depend on the \prologflag{character_escapes} Prolog flag. \end{description} \subsection{Convenient functions to generate Prolog exceptions} \label{sec:cerror} The typical implementation of a foreign predicate first uses the PL_get_*() functions to extract C data types from the Prolog terms. Failure of any of these functions is normally because the Prolog term is of the wrong type. The *_ex() family of functions are wrappers around (mostly) the PL_get_*() functions, such that we can write code in the style below and get proper exceptions if an argument is uninstantiated or of the wrong type. \Secref{pl-cvt-functions} documents an alternative API to fetch values for the C basic types. \begin{code} /** set_size(+Name:atom, +Width:int, +Height:int) is det. static foreign_t set_size(term_t name, term_t width, term_t height) { char *n; int w, h; if ( !PL_get_chars(name, &n, CVT_ATOM|CVT_EXCEPTION) || !PL_get_integer_ex(with, &w) || !PL_get_integer_ex(height, &h) ) return FALSE; ... } \end{code} \noindent \begin{description} \cfunction{int}{PL_get_atom_ex}{term_t t, atom_t *a} As \cfuncref{PL_get_atom}{}, but raises a type or instantiation error if \arg{t} is not an atom. \cfunction{int}{PL_get_integer_ex}{term_t t, int *i} As \cfuncref{PL_get_integer}{}, but raises a type or instantiation error if \arg{t} is not an integer, or a representation error if the Prolog integer does not fit in a C \ctype{int}. \cfunction{int}{PL_get_long_ex}{term_t t, long *i} As \cfuncref{PL_get_long}{}, but raises a type or instantiation error if \arg{t} is not an atom, or a representation error if the Prolog integer does not fit in a C \ctype{long}. \cfunction{int}{PL_get_int64_ex}{term_t t, int64_t *i} As \cfuncref{PL_get_int64}{}, but raises a type or instantiation error if \arg{t} is not an integer, or a representation error if the Prolog integer does not fit in a C \ctype{int64_t}. \cfunction{int}{PL_get_uint64_ex}{term_t t, uint64_t *i} As \cfuncref{PL_get_uint64}{}, but raises a type, domain or instantiation error if \arg{t} is not an integer or \arg{t} is less than zero, or a representation error if the Prolog integer does not fit in a C \ctype{int64_t}. \cfunction{int}{PL_get_intptr_ex}{term_t t, intptr_t *i} As \cfuncref{PL_get_intptr}{}, but raises a type or instantiation error if \arg{t} is not an atom, or a representation error if the Prolog integer does not fit in a C \ctype{intptr_t}. \cfunction{int}{PL_get_size_ex}{term_t t, size_t *i} As \cfuncref{PL_get_size}{}, but raises a type or instantiation error if \arg{t} is not an atom, or a representation error if the Prolog integer does not fit in a C \ctype{size_t}. \cfunction{int}{PL_get_bool_ex}{term_t t, int *i} As \cfuncref{PL_get_bool}{}, but raises a type or instantiation error if \arg{t} is not a valid boolean value (\const{true}, \const{false}, \const{on}, const{off}, \const{1} or \const{0}). Note that the pointer is to an \ctype{int} because C has no \ctype{bool} type. \cfunction{int}{PL_get_float_ex}{term_t t, double *f} As \cfuncref{PL_get_float}{}, but raises a type or instantiation error if \arg{t} is not a float. \cfunction{int}{PL_get_char_ex}{term_t t, int *p, int eof} Get a character code from \arg{t}, where \arg{t} is either an integer or an atom with length one. If \arg{eof} is \const{TRUE} and \arg{t} is -1, \arg{p} is filled with -1. Raises an appropriate error if the conversion is not possible. \cfunction{int}{PL_get_pointer_ex}{term_t t, void **addrp} As \cfuncref{PL_get_pointer}{}, but raises a type or instantiation error if \arg{t} is not a pointer. \cfunction{int}{PL_get_list_ex}{term_t l, term_t h, term_t t} As \cfuncref{PL_get_list}{}, but raises a type or instantiation error if \arg{t} is not a list. \cfunction{int}{PL_get_nil_ex}{term_t l} As \cfuncref{PL_get_nil}{}, but raises a type or instantiation error if \arg{t} is not the empty list. Because \cfuncref{PL_get_nil_ex}{} is commonly used after a \exam{while} loop over \cfuncref{PL_get_list_ex}{}, it fails immediately if there is an exception pending (from \cfuncref{PL_get_list_ex}{}). \cfunction{int}{PL_unify_list_ex}{term_t l, term_t h, term_t t} As \cfuncref{PL_unify_list}{}, but raises a type error if \arg{t} is not a variable, list-cell or the empty list. \cfunction{int}{PL_unify_nil_ex}{term_t l} As \cfuncref{PL_unify_nil}{}, but raises a type error if \arg{t} is not a variable, list-cell or the empty list. \cfunction{int}{PL_unify_bool_ex}{term_t t, int val} As \cfuncref{PL_unify_bool}{}, but raises a type error if \arg{t} is not a variable or a boolean. \end{description} The second family of functions in this section simplifies the generation of ISO compatible error terms. Any foreign function that calls this function must return to Prolog with the return code of the error function or the constant \const{FALSE}. If available, these error functions add the name of the calling predicate to the error context. See also \cfuncref{PL_raise_exception}{}. \begin{description} \cfunction{int}{PL_instantiation_error}{term_t culprit} Raise \const{instantiation_error}. \arg{Culprit} is ignored, but should be bound to the term that is insufficiently instantiated. See \index{instantiation_error/1}\predref{instantiation_error}{1}. \cfunction{int}{PL_uninstantiation_error}{term_t culprit} Raise \exam{uninstantiation_error(culprit)}. This should be called if an argument that must be unbound at entry is bound to \arg{culprit}. This error is typically raised for a pure output arguments such as a newly created stream handle (e.g., the third argument of \index{open/3}\predref{open}{3}). \cfunction{int}{PL_representation_error}{const char *resource} Raise \exam{representation_error(resource)}. See \index{representation_error/1}\predref{representation_error}{1}. \cfunction{int}{PL_type_error}{const char *expected, term_t culprit} Raise \exam{type_error(expected, culprit)}. See \index{type_error/2}\predref{type_error}{2}. \cfunction{int}{PL_domain_error}{const char *expected, term_t culprit} Raise \exam{domain_error(expected, culprit)}. See \index{domain_error/2}\predref{domain_error}{2}. \cfunction{int}{PL_existence_error}{const char *type, term_t culprit} Raise \exam{existence_error(type, culprit)}. See \index{type_error/2}\predref{type_error}{2}. \cfunction{int}{PL_permission_error}{const char *operation, const char *type, term_t culprit} Raise \exam{permission_error(operation, type, culprit)}. See \index{permission_error/3}\predref{permission_error}{3}. \cfunction{int}{PL_resource_error}{const char *resource} Raise \exam{resource_error(resource)}. See \index{resource_error/1}\predref{resource_error}{1}. \cfunction{int}{PL_syntax_error}{const char *message, IOSTREAM *in} Raise \exam{syntax_error(message)}. If \arg{arg} is not \const{NULL}, add information about the current position of the input stream. \end{description} \subsection{Foreign language wrapper support functions} \label{sec:pl-cvt-functions} In addition to the functions described in \secref{foreign-extract-from-term}, there is a family of functions that is used for automatic generation of wrapper functions, for example using the Prolog library \pllib{qpforeign} that provides a Quintus/SICStus compatible foreign language interface. The PL_cvt_i_*() family of functions is suitable for use with a \exam{_Generic} selector or C++ overloading.\footnote{\exam{_Generic} needs to take into account that there's no \ctype{bool} type in C but there is in C++. An overloaded integer() method is provided in the C++ interface.} Note that the documentation on this API is incomplete. Also note that many of these functions are equivalent to the PL_get_*_ex() functions described in \secref{cerror}. \begin{description} \cfunction{int}{PL_cvt_i_bool}{term_t p, int *c} Equivalent to \cfuncref{PL_get_bool_ex}{}. Note that the pointer is to an \ctype{int} because C has no \ctype{bool} type. The return value is either \const{0} or \const{1}. \cfunction{int}{PL_cvt_i_char}{term_t p, char *c} \nodescription \cfunction{int}{PL_cvt_i_schar}{term_t p, signed char *c} \nodescription \cfunction{int}{PL_cvt_i_uchar}{term_t p, unsigned char *c} \nodescription \cfunction{int}{PL_cvt_i_short}{term_t p, short *s} \nodescription \cfunction{int}{PL_cvt_i_ushort}{term_t p, unsigned short *s} \nodescription \cfunction{int}{PL_cvt_i_int}{term_t p, int *c} \nodescription \cfunction{int}{PL_cvt_i_uint}{term_t p, unsigned int *c} \nodescription \cfunction{int}{PL_cvt_i_long}{term_t p, long *c} \nodescription \cfunction{int}{PL_cvt_i_ulong}{term_t p, unsigned long *c} \nodescription \cfunction{int}{PL_cvt_i_llong}{term_t p, long long *c} \nodescription \cfunction{int}{PL_cvt_i_ullong}{term_t p, unsigned long long *c} \nodescription \cfunction{int}{PL_cvt_i_int32}{term_t p, int32_t *c} \nodescription \cfunction{int}{PL_cvt_i_uint32}{term_t p, uint32_t *c} \nodescription \cfunction{int}{PL_cvt_i_int64}{term_t p, int64_t *c} \nodescription \cfunction{int}{PL_cvt_i_uint64}{term_t p, uint64_t *c} \nodescription \cfunction{int}{PL_cvt_i_size_t}{term_t p, size_t *c} Convert a Prolog integer into a C integer of the specified size. Generate an exception and return \const{FALSE} if the conversion is impossible because the Prolog term is not an integer or the C type cannot represent the value of the Prolog integer. \end{description} \subsection{Serializing and deserializing Prolog terms} \label{sec:foreign-serialize} \begin{description} \cfunction{int}{PL_put_term_from_chars}{term_t t, int flags, size_t len, const char *s} Parse the text from the C-string \arg{s} holding \arg{len} bytes and put the resulting term in \arg{t}. \arg{len} can be \exam{(size_t)-1}, assuming a 0-terminated string. The \arg{flags} argument controls the encoding and is currently one of \const{REP_UTF8} (string is UTF8 encoded), \const{REP_MB} (string is encoded in the current locale) or 0 (string is encoded in ISO latin 1). The string may, but is not required, to be closed by a full stop (.). If parsing produces an exception; the behaviour depends on the \const{CVT_EXCEPTION} flag. If present, the exception is propagated into the environment. Otherwise, the exception is placed in \arg{t} and the return value is \const{FALSE}.\footnote{The \const{CVT_EXCEPTION} was added in version 8.3.12}. \end{description} \subsection{BLOBS: Using atoms to store arbitrary binary data} \label{sec:blob} \index{Java}\index{COM}% SWI-Prolog atoms as well as strings can represent arbitrary binary data of arbitrary length. This facility is attractive for storing foreign data such as images in an atom. An atom is a unique handle to this data and the atom garbage collector is able to destroy atoms that are no longer referenced by the Prolog engine. This property of atoms makes them attractive as a handle to foreign resources, such as Java atoms, Microsoft's COM objects, etc., providing safe combined garbage collection. To exploit these features safely and in an organised manner, the SWI-Prolog foreign interface allows creating `atoms' with additional type information. The type is represented by a structure holding C function pointers that tell Prolog how to handle releasing the atom, writing it, sorting it, etc. Two atoms created with different types can represent the same sequence of bytes. Atoms are first ordered on the rank number of the type and then on the result of the \cfuncref{compare}{} function. Rank numbers are assigned when the type is registered. This implies that the results of inequality comparisons between blobs of different types is undefined and can change if the program is run twice (the ordering within a blob type will not change, of course). While the blob is alive, neither its handle nor the location of the contents (see \cfuncref{PL_blob_data}{}) change. If the blob's type has the \const{PL_BLOB_UNIQUE} feature, the content of the blob must remain unmodified. Blobs are \emph{only} reclaimed by the atom garbage collector. In this case the atom garbage collector calls the \cfuncref{release}{} function associated with the blob type and reclaims the memory allocated for the content unless this is owned by the creator of the blob indicated by the \const{PL_BLOB_NOCOPY} flag. After an \ctype{atom_t} value is reclaimed by the atom garbage collector, the value may be reused for allocating a new blob or atom. If foreign code stores the \ctype{atom_t} handle in some permanent location it must make sure the handle is \jargon{registered} to prevent it from being garbage collected. If the handle is obtained from a \ctype{term_t} object it is \textbf{not} registered because it is protected by the \ctype{term_t} object. This applies to e.g., \cfuncref{PL_get_atom}{}. Functions that create a handle from data such as \cfuncref{PL_new_atom}{} return a registered handle to prevent the asynchronous atom garbage collector from reclaiming it immediately. Note that many of the API functions create an atom or blob handle and use this to fill a \ctype{term_t} object, e.g., \cfuncref{PL_unify_blob}{}, \cfuncref{PL_unify_chars}{}, etc. In this scenario the handle is protected by the \ctype{term_t} object. Registering and unregistering \ctype{atom_t} handles is done by \cfuncref{PL_register_atom}{} and \cfuncref{PL_unregister_atom}{}. Note that during program shutdown using \cfuncref{PL_cleanup}{}, all atoms and blobs are reclaimed as described above. \textbf{These objects are reclaimed regardless of their registration count. The order in which the atoms or blobs are reclaimed under \cfuncref{PL_cleanup}{} is undefined.} However, when these objects are reclaimed using \index{garbage_collect_atoms/0}\predref{garbage_collect_atoms}{0}, registration counts are taken into account. \subsubsection{Defining a BLOB type} \label{sec:blobtype} The type \ctype{PL_blob_t} represents a structure with the layout displayed below. The structure contains additional fields at the \ldots for internal bookkeeping as well as future extensions. \begin{code} typedef struct PL_blob_t { uintptr_t magic; /* PL_BLOB_MAGIC */ uintptr_t flags; /* Bitwise or of PL_BLOB_* */ const char * name; /* name of the type */ int (*release)(atom_t a); int (*compare)(atom_t a, atom_t b); int (*write)(IOSTREAM *s, atom_t a, int flags); void (*acquire)(atom_t a); int (*save)(atom_t a, IOSTREAM *s); atom_t (*load)(IOSTREAM *s); ... } PL_blob_t; \end{code} \noindent For each type, exactly one such structure should be allocated. Its first field must be initialised to \const{PL_BLOB_MAGIC}. If a blob type is registered from a loadable object (shared object or DLL) the blob type must be deregistered using \cfuncref{PL_unregister_blob_type}{} before the object may be released. The \arg{flags} is a bitwise \emph{or} of the following constants: \begin{description} \constitem{PL_BLOB_TEXT} If specified, the blob is assumed to contain text and is considered a normal Prolog atom. The (currently) two predefined blob types that represent atoms have this flag set. User-defined blobs may not specify this, even if they contain only text. Applications should \emph{not} use the blob API to create normal text atoms or get access to the text represented by normal text atoms. Most applications should use \cfuncref{PL_get_nchars}{} and \cfuncref{PL_unify_chars}{} to get text from Prolog terms or create Prolog terms that represent text. \constitem{PL_BLOB_UNIQUE} If specified the system ensures that the blob-handle is a unique reference for a blob with the given type, length and content. If this flag is not specified, each lookup creates a new blob. Uniqueness is determined by comparing the bytes in the blobs unless \const{PL_BLOB_NOCOPY} is also specified, in which case the pointers are compared. \constitem{PL_BLOB_NOCOPY} By default the content of the blob is copied. Using this flag the blob references the external data directly. The user must ensure the provided pointer is valid as long as the atom lives. If \const{PL_BLOB_UNIQUE} is also specified, uniqueness is determined by comparing the pointer rather than the data pointed at. Using \const{PL_BLOB_UNIQUE\chr{\Sbar}PL_BLOB_NOCOPY} can be used to make a blob reference an arbitrary pointer where the pointer data may be reclaimed in the release() handler. \constitem{PL_BLOB_WCHAR} If \const{PL_BLOB_TEXT} is also set, then the text is made up of \const{pl_wchar_t} items and the blob's lenght is the number of bytes (that is, the number of characters times \exam{sizeof(pl_wchar_t)}). As \const{PL_BLOB_TEXT}, this flag should not be set in user-defined blobs. \end{description} The \arg{name} field represents the type name as available to Prolog. See also \index{current_blob/2}\predref{current_blob}{2}. The other fields are function pointers that must be initialised to proper functions or \const{NULL} to get the default behaviour of built-in atoms. Below are the defined member functions: \begin{description} \cfunction{void}{acquire}{atom_t a} Called if a new blob of this type is created through \cfuncref{PL_put_blob}{}, \cfuncref{PL_unify_blob}{}, or \cfuncref{PL_new_blob}{}. Note this this call is done as part of creating the blob. The call to \cfuncref{PL_unify_blob}{} may fail if the unification fails or cannot be completed due to a resource error. \cfuncref{PL_put_blob}{} has no such error conditions. This callback is typically used to store the \ctype{atom_t} handle into the content of the blob. Given a pointer to the content, we can now use \cfuncref{PL_unify_atom}{} to bind a Prolog term with a reference to the pointed to object. If the content of the blob can be modified (\const{PL_BLOB_UNIQUE} is not present) this is the only way to get access to the \ctype{atom_t} handle that belongs to this blob. If \const{PL_BLOB_UNIQUE} is provided and respected, \cfuncref{PL_unify_blob}{} given the same pointer and length will produce the same \const{atom_t} handle. \cfunction{int}{release}{atom_t a} The blob (atom) \arg{a} is about to be released. This function can retrieve the data of the blob using \cfuncref{PL_blob_data}{}. If it returns \const{FALSE}, the atom garbage collector will \emph{not} reclaim the atom. The \cfuncref{release}{} function is called when the atom is reclaimed by the atom garbage collector. For critical resources such as file handles or significant memory resources it may be desirable to have an explicit call to dispose (most of) the resources. For example, \index{close/1}\predref{close}{1} reclaims the file handle and most of the resources associated with a stream, leaving only a tiny bit of content to the garbage collector. See also \index{setup_call_cleanup/3}\predref{setup_call_cleanup}{3}. The release() callback is called in the context of the thread executing the atom garbage collect. Normally the thread \const{gc} runs all atom and clause garbage collections. The release() function may not call any of the PL_*() functions except for \cfuncref{PL_unregister_atom}{} to unregister other atoms that are part data associated to the blob. Calling any of the other PL_* functions may return in deadlocks or crashes. The release() function should not call any potentially slow or blocking functions as this may cause serious slowdowns in the rest of the system. Blobs that require cleanup that is slow, blocking or requires calling Prolog must pass the data to be cleaned to another thread. Be aware that if the blob uses \const{PL_BLOB_NOCOPY} the user is responsible for discarding the data, otherwise the atom garbage collector will free the data. As SWI-Prolog atom garbage collector is \jargon{conservative}, there is no guarantee that the release() function will ever be called. If it is important to clean up some resource, there should be an explicit predicate for doing that, and calling that predicate should be guaranteed by using \index{setup_call_cleanup/3}\predref{setup_call_cleanup}{3} or some a process finalization hook such as \index{at_halt/1}\predref{at_halt}{1}. Normally, Prolog does not clean memory during shutdown. It does so on an explicit call to \cfuncref{PL_cleanup}{}.\footnote{Or if the system is compiled with the \program{cmake} \jargon{build type} \const{Debug}.} In such a situation, there is no guarantee of the order in which atoms are released; if a blob contains an atom (or another blob), those atoms (or blobs) may have already been released. See also \cfuncref{PL_blob_data}{}. \cfunction{int}{compare}{atom_t a, atom_t b} Compare the blobs \arg{a} and \arg{b}, both of which are of the type associated to this blob type. Return values are as memcmp(): $< 0$ if \arg{a} is less than \arg{b}, $= 0$ if both are equal, and $> 0$ otherwise. The default implementation is a bitwise comparison of the blobs' contents. If you cannot guarantee that the blobs all have unique contents, then you should incorporate the blob address (the system guarantees that blobs are not shifted in memory after they are allocated). This function should not call any PL_*() functions other than \cfuncref{PL_blob_data}{}. The following minimal compare function gives a stable total ordering: \begin{code} static int compare_my_blob(atom_t a, atom_t b) { const struct my_blob_data *blob_a = PL_blob_data(a, NULL, NULL); const struct my_blob_data *blob_b = PL_blob_data(b, NULL, NULL); return (blob_a > blob_b) ? 1 : (blob_a < blob_b) ? -1 : 0; } \end{code} \noindent \cfunction{int}{write}{IOSTREAM *s, atom_t a, int flags} Write the content of the blob \arg{a} to the stream \arg{s} respecting the \arg{flags}. The return value is \const{TRUE} or \const{FALSE} and does \emph{not} follow the Unix convention of the number of bytes (where zero is possible) and negative for errors. Any I/O operations to \arg{s} are in the context of a \cfuncref{PL_acquire_stream}{}; upon return, the \cfuncref{PL_release_stream}{} handles any errors, so it is safe to not check return codes from \cfuncref{Sprintf}{}, etc. In general, the output from the write() callback should be minimal. If you wish to output more debug information, it is suggested that you either add a debug option to your "open" predicate to output more information, or provide a "properties" predicate. A typical implementation is: \begin{code} static int write_my_blob(IOSTREAM *s, atom_t symbol, int flags) { (void)flags; /* unused */ Sfprintf(s, "(%p)", PL_blob_data(symbol, NULL, NULL)); return TRUE; } \end{code} \noindent The \arg{flags} are a bitwise \emph{or} of zero or more of the \const{PL_WRT_*} flags that were passed in to the calling \cfuncref{PL_write_term}{} that called write(), and are defined in \file{SWI-Prolog.h}. The \arg{flags} do not have the \const{PL_WRT_NEWLINE} bit set, so it is safe to call \cfuncref{PL_write_term}{} and there is no need for writing a trailing newline. This prototype is available if the \file{SWI-Stream.h} is included \emph{before} \file{SWI-Prolog.h}. This function can retrieve the data of the blob using \cfuncref{PL_blob_data}{}. Most blobs reference some external data identified by a pointer and the write() function writes \verb$<$\arg{type}\verb$>($\arg{address}\verb$)$. If this function is not provided, \index{write/1}\predref{write}{1} emits the content of the blob for blobs of type \const{PL_BLOB_TEXT} or a string of the format \verb$<#$\textit{hex data}\verb$>$ for binary blobs. \end{description} \begin{description} \cfunction{int}{save}{atom_t a, IOSTREAM *s} Write the blob to stream \arg{s}, in an opaque form that is known only to the blob. If a ``save'' function is not provided (that is, the field is \const{NULL}), the default implementation saves and restores the blob as if it is an array of bytes which may contain null (\exam{'\\0'}) bytes. \file{SWI-Stream.h} defines a number of PL_qlf_put_*() functions that write data in a machine-independent form that can be read by the corresponding PL_qlf_get_*() functions. If the ``save'' function encounters an error, it should call \cfuncref{PL_warning}{}, raise an exception (see \cfuncref{PL_raise_exception}{}), and return \const{FALSE}.\footnote{Details are subject to change.} Note that failure to save/restore a blob makes it impossible to compile a file that contains such a blob using \index{qcompile/2}\predref{qcompile}{2} as well as creating a \jargon{saved state} from a program that contains such a blob impossible. Here, \jargon{contains} means that the blob appears in a clause or directive. \cfunction{atom_t}{load}{IOSTREAM *s} Read the blob from its saved form as written by the ``save'' function of the same blob type. If this cannot be done (e.g., a stream read failure or a corrupted external form), the ``load'' function should call \cfuncref{PL_warning}{}, then \cfuncref{PL_fatal_error}{}, and return const{FALSE}.\footnote{Details are subject to change; see the ``save'' function.} If a ``load'' function is not provided (that is, the field is \const{NULL}, the default implementation assumes that the blob was written by the default ``save'' - that is, as an array of bytes \file{SWI-Stream.h} defines a number of PL_qlf_get_*() functions that read data in a machine-independent form, as written by the by the corresponding PL_qlf_put_*() functions. The atom that the ``load'' function returns can be created using \cfuncref{PL_new_blob}{}. \cfunction{int}{PL_unregister_blob_type}{PL_blob_t *type} Unlink the blob type from the registered type and transform the type of possible living blobs to \const{unregistered}, avoiding further reference to the type structure, functions referred by it, as well as the data. This function returns \const{TRUE} if no blobs of this type existed and \const{FALSE} otherwise. \cfuncref{PL_unregister_blob_type}{} is intended for the uninstall() hook of foreign modules, avoiding further references to the module. \cfunction{int}{PL_register_blob_type}{PL_blob_t *type} This function does not need to be called explicitly. It is called if needed when a blob is created by \cfuncref{PL_unify_blob}{}, \cfuncref{PL_put_blob}{}, or \cfuncref{PL_new_blob}{}. \end{description} \subsubsection{Accessing blobs} \label{sec:blobaccess} The blob access functions are similar to the atom accessing functions. Blobs being atoms, the atom functions operate on blobs and vice versa. For clarity and possible future compatibility issues, however, it is not advised to rely on this. \begin{description} \cfunction{int}{PL_is_blob}{term_t t, PL_blob_t **type} Succeeds if \arg{t} refers to a blob, in which case \arg{type} is filled with the type of the blob. \cfunction{int}{PL_unify_blob}{term_t t, void *blob, size_t len, PL_blob_t *type} Unify \arg{t} to a blob constructed from the given data and associated with the given type. This performs the following steps: \begin{enumerate} \item If the \arg{type} has \const{PL_BLOB_UNIQUE} set, search the blob database for a blob of the same type with the same content. If found, unify \arg{t} with the existing handle. \item If not found or \const{PL_BLOB_UNIQUE} is not set, create a new blob handle. If \const{PL_BLOB_NOCOPY} is set, associate it to the given memory; else, copy the memory to a new area owned by the blob. Call the \cfuncref{acquire}{} function of the \arg{type}. \item Unify \arg{t} with the existing or new handle. This succeeds if \arg{t} is already bound to the existing blob handle. If \arg{t} is a variable, it succeeds \emph{if} sufficient resources are available to perform the unification; if \arg{t} is bound to something else, this fails. \end{enumerate} It is possible that a blob referencing critial resources is created after which the unification fails. Typically these resources are eventually reclaimed because the new blob is not referenced and reclaimed by the atom garbage collector. As described with the \cfuncref{release}{} function, it can be desirable to reclaim the critical resources after the failing \cfuncref{PL_unify_blob}{} call. \cfunction{int}{PL_put_blob}{term_t t, void *blob, size_t len, PL_blob_t *type} Store the described blob in \arg{t}. The return value indicates whether a new blob was allocated (\const{FALSE}) or the blob is a reference to an existing blob (\const{TRUE}). Reporting new/existing can be used to deal with external objects having their own reference counts. If the return is \const{TRUE} this reference count must be incremented, and it must be decremented on blob destruction callback. See also \cfuncref{PL_put_atom_nchars}{}. \cfunction{atom_t}{PL_new_blob}{void *blob, size_t len, PL_blob_t *type} Create a blob from its internal opaque form. This function is intended for the ``load'' function of a blob. \cfunction{int}{PL_get_blob}{term_t t, void **blob, size_t *len, PL_blob_t **type} If \arg{t} holds a blob or atom, get the data and type and return \const{TRUE}. Otherwise return \const{FALSE}. Each result pointer may be \const{NULL}, in which case the requested information is ignored. \cfunction{void *}{PL_blob_data}{atom_t a, size_t *len, PL_blob_t **type} Get the data and type associated to a blob. This function is mainly used from the callback functions described in \secref{blobtype}. Note that if the release() hook is called from \cfuncref{PL_cleanup}{}, blobs are released regardless of whether or not they are referenced and the order in which blobs are released is undefined (the order depends on the ordering in the atom hash table). \cfuncref{PL_blob_data}{} may be called safely on a blob that has already been released. If this happens during \cfuncref{PL_cleanup}{} the return value is guaranteed to be \const{NULL}. During normal execution it may return the content of a newly allocated blob that reuses the released handle. \cfunction{int}{PL_free_blob}{atom_t blob} New in 9.1.12. This function may be used on blobs with the \const{PL_BLOB_NOCOPY} flag set and a release() function. It causes the release() function to be called, after which the data and size are set to 0. The related atom remains existent and accessing it as a blob returns \const{NULL} for the data and 0 for the size. \end{description} \subsection{Exchanging GMP numbers} \label{sec:gmpforeign} If SWI-Prolog is linked with the GNU Multiple Precision Arithmetic Library (GMP, used by default), the foreign interface provides functions for exchanging numeric values to GMP types. To access these functions the header \verb$$ must be included \emph{before} \verb$$. Foreign code using GMP linked to SWI-Prolog asks for some considerations. \begin{itemize} \item SWI-Prolog normally rebinds the GMP allocation functions using mp_set_memory_functions(). This means SWI-Prolog must be initialised before the foreign code touches any GMP function. You can call \verb$PL_action(PL_GMP_SET_ALLOC_FUNCTIONS, TRUE)$ to force Prolog's GMP initialization without doing the rest of the Prolog initialization. If you do not want Prolog rebinding the GMP allocation, call \verb$PL_action(PL_GMP_SET_ALLOC_FUNCTIONS, FALSE)$ \emph{before} initializing Prolog. \item On Windows, each DLL has its own memory pool. To make exchange of GMP numbers between Prolog and foreign code possible you must either let Prolog rebind the allocation functions (default) or you must recompile SWI-Prolog to link to a DLL version of the GMP library. \end{itemize} Here is an example exploiting the function mpz_nextprime(): \begin{code} #include #include static foreign_t next_prime(term_t n, term_t prime) { mpz_t mpz; int rc; mpz_init(mpz); if ( PL_get_mpz(n, mpz) ) { mpz_nextprime(mpz, mpz); rc = PL_unify_mpz(prime, mpz); } else rc = FALSE; mpz_clear(mpz); return rc; } install_t install() { PL_register_foreign("next_prime", 2, next_prime, 0); } \end{code} \noindent \begin{description} \cfunction{int}{PL_get_mpz}{term_t t, mpz_t mpz} If \arg{t} represents an integer, \arg{mpz} is filled with the value and the function returns \const{TRUE}. Otherwise \arg{mpz} is untouched and the function returns \const{FALSE}. Note that \arg{mpz} must have been initialised before calling this function and must be cleared using mpz_clear() to reclaim any storage associated with it. \cfunction{int}{PL_get_mpq}{term_t t, mpq_t mpq} If \arg{t} is an integer or rational number (term \functor{rdiv}{2}), \arg{mpq} is filled with the \emph{normalised} rational number and the function returns \const{TRUE}. Otherwise \arg{mpq} is untouched and the function returns \const{FALSE}. Note that \arg{mpq} must have been initialised before calling this function and must be cleared using mpq_clear() to reclaim any storage associated with it. \cfunction{int}{PL_unify_mpz}{term_t t, mpz_t mpz} Unify \arg{t} with the integer value represented by \arg{mpz} and return \const{TRUE} on success. The \arg{mpz} argument is not changed. \cfunction{int}{PL_unify_mpq}{term_t t, mpq_t mpq} Unify \arg{t} with a rational number represented by \arg{mpq} and return \const{TRUE} on success. Note that \arg{t} is unified with an integer if the denominator is 1. The \arg{mpq} argument is not changed. \end{description} \subsection{Calling Prolog from C} \label{sec:calling-prolog-from-c} The Prolog engine can be called from C. There are two interfaces for this. For the first, a term is created that could be used as an argument to \index{call/1}\predref{call}{1}, and then \cfuncref{PL_call}{} is used to call Prolog. This system is simple, but does not allow to inspect the different answers to a non-deterministic goal and is relatively slow as the runtime system needs to find the predicate. The other interface is based on \cfuncref{PL_open_query}{}, \cfuncref{PL_next_solution}{}, and \cfuncref{PL_cut_query}{} or \cfuncref{PL_close_query}{}. This mechanism is more powerful, but also more complicated to use. \subsubsection{Predicate references} \label{sec:foreign-predicate-handle} This section discusses the functions used to communicate about predicates. Though a Prolog predicate may be defined or not, redefined, etc., a Prolog predicate has a handle that is neither destroyed nor moved. This handle is known by the type \ctype{predicate_t}. \begin{description} \cfunction{predicate_t}{PL_pred}{functor_t f, module_t m} Return a handle to a predicate for the specified name/arity in the given module. If the module argument \arg{m} is \const{NULL}, the current context module is used. If the target predicate does not exist a handle to a new \textit{undefined} predicate is returned. The predicate may fail, returning \exam{(predicate_t)0} after setting a resource exception, if the target module has a limit on the \const{program_space}, see \index{set_module/1}\predref{set_module}{1}. Currently aborts the process with a \jargon{fatal error} when out of memory. Future versions may raise a resource exception and return \exam{(predicate_t)0}. \cfunction{predicate_t}{PL_predicate}{const char *name, int arity, const char* module} Same as \cfuncref{PL_pred}{}, but provides a more convenient interface to the C programmer. If the module argument \arg{module} is \const{NULL}, the current context module is used. The \ctype{predicate_t} handle may be stored as global data and reused for future queries\footnote{\cfuncref{PL_predicate}{} involves 5 hash lookups (two to get the atoms, one to get the module, one to get the functor and the final one to get the predicate associated with the functor in the module)} as illustrated below. \begin{code} static predicate_t p = 0; ... if ( !p ) p = PL_predicate("is_a", 2, "database"); \end{code} \noindent Note that \cfuncref{PL_cleanup}{} invalidates the predicate handle. Foreign libraries that use the above mechanism must implement the module uninstall() function to clear the \ctype{predicate_t} global variable. \cfunction{int}{PL_predicate_info}{predicate_t p, atom_t *n, size_t *a, module_t *m} Return information on the predicate \arg{p}. The name is stored over \arg{n}, the arity over \arg{a}, while \arg{m} receives the definition module. Note that the latter need not be the same as specified with \cfuncref{PL_predicate}{}. If the predicate is imported into the module given to \cfuncref{PL_predicate}{}, this function will return the module where the predicate is defined. Any of the arguments \arg{n}, \arg{a} and \arg{m} can be \const{NULL}. Currently always returns \const{TRUE}. \end{description} \subsubsection{Initiating a query from C} \label{sec:foreign-create-query} This section discusses the functions for creating and manipulating queries from C. Note that a foreign context can have at most one active query. This implies that it is allowed to make strictly nested calls between C and Prolog (Prolog calls C, calls Prolog, calls C, etc.), but it is \strong{not} allowed to open multiple queries and start generating solutions for each of them by calling \cfuncref{PL_next_solution}{}. Be sure to call \cfuncref{PL_cut_query}{} or \cfuncref{PL_close_query}{} on any query you opened before opening the next or returning control back to Prolog. Failure to do so results in "undefined behavior" (typically, a crash). \begin{description} \cfunction{qid_t}{PL_open_query}{module_t ctx, int flags, predicate_t p, term_t +t0} Opens a query and returns an identifier for it. \arg{ctx} is the {\em context module} of the goal. When \const{NULL}, the context module of the calling context will be used, or \const{user} if there is no calling context (as may happen in embedded systems). Note that the context module only matters for \jargon{meta-predicates}. See \index{meta_predicate/1}\predref{meta_predicate}{1}, \index{context_module/1}\predref{context_module}{1} and \index{module_transparent/1}\predref{module_transparent}{1}. The term reference \arg{t0} is the first of a vector of term references as returned by \cfuncref{PL_new_term_refs}{n}. Raise a resource exception and returns \exam{(qid_t)0} on failure. Every use of \cfuncref{PL_open_query}{} must have a corresponding call to \cfuncref{PL_cut_query}{} or \cfuncref{PL_close_query}{} before the foreign predicate returns either \const{TRUE} or \const{FALSE}. The \arg{flags} arguments provides some additional options concerning debugging and exception handling. It is a bitwise \emph{or} of the following values below. Note that exception propagation is defined by the flags \const{PL_Q_NORMAL}, \const{PL_Q_CATCH_EXCEPTION} and \const{PL_Q_PASS_EXCEPTION}. Exactly one of these flags must be specified (if none of them is specified, the behavior is as if \const{PL_Q_NODEBUG} is specified).. \begin{description} \definition{\const{PL_Q_NORMAL}} Normal operation. It is named "normal" because it makes a call to Prolog behave as it did before exceptions were implemented, i.e., an error (now uncaught exception) triggers the debugger. See also the Prolog flag \prologflag{debug_on_error}. This mode is still useful when calling Prolog from C if the C code is not willing to handle exceptions. \definition{\const{PL_Q_NODEBUG}} Switch off the debugger while executing the goal. This option is used by many calls to hook-predicates to avoid tracing the hooks. An example is \index{print/1}\predref{print}{1} calling \index{portray/1}\predref{portray}{1} from foreign code. This is the default if flags is \const{0}. \definition{\const{PL_Q_CATCH_EXCEPTION}} If an exception is raised while executing the goal, make it available by calling \exam{\cfuncref{PL_exception}{qid}}, where \exam{qid} is the \ctype{qid_t} returned by \cfuncref{PL_open_query}{}. The exception is implicitly cleared from the environment when the query is closed and the exception term returned from \exam{\cfuncref{PL_exception}{qid}} becomes invalid. Use \const{PL_Q_PASS_EXCEPTION} if you wish to propagate the exception. \definition{\const{PL_Q_PASS_EXCEPTION}} As \const{PL_Q_CATCH_EXCEPTION}, making the exception on the inner environment available using \exam{\cfuncref{PL_exception}{0}} in the parent environment. If \cfuncref{PL_next_solution}{} returns \const{FALSE}, you must call \cfuncref{PL_cut_query}{} or \cfuncref{PL_close_query}{}. After that you may verify whether failure was due to logical failure of the called predicate or an exception by calling \exam{\cfuncref{PL_exception}{0}}. If the predicate failed due to an exception you should return with \const{FALSE} from the foreign predicate or call \cfuncref{PL_clear_exception}{} to clear it. If you wish to process the exception in C, it is advised to use \const{PL_Q_CATCH_EXCEPTION} instead, but only if you have no need to raise an exception or re-raise the caught exception. Note that \const{PL_Q_PASS_EXCEPTION} is used by the debugger to decide whether the exception is \jargon{caught}. If there is no matching \index{catch/3}\predref{catch}{3} call in the current query and the query was started using \const{PL_Q_PASS_EXCEPTION} the debugger searches the parent queries until it either finds a matching \index{catch/3}\predref{catch}{3}, a query with \const{PL_Q_CATCH_EXCEPTION} (in which case it considers the exception handled by C) or the top of the query stack (in which case it considers the exception \jargon{uncaught}). Uncaught exceptions use the \pllib{library(prolog_stack)} to add a backtrace to the exception and start the debugger as soon as possible if the Prolog flag \prologflag{debug_on_error} is \const{true}. \definition{\const{PL_Q_ALLOW_YIELD}} Support the \const{I_YIELD} instruction for engine-based coroutining. See \nopredref{\$engine_yield}{2} in \file{boot/init.pl} for details. \definition{\const{PL_Q_EXT_STATUS}} Make \cfuncref{PL_next_solution}{} return extended status. Instead of only \const{TRUE} or \const{FALSE} extended status as illustrated in the following table: \begin{center} \begin{tabular}{llp{4in}} \bf Extended & \bf Normal & \\ \hline PL_S_EXCEPTION & FALSE & Exception available through \cfuncref{PL_exception}{} \\ PL_S_FALSE & FALSE & Query failed \\ PL_S_TRUE & TRUE & Query succeeded with choicepoint \\ PL_S_LAST & TRUE & Query succeeded without choicepoint \\ \end{tabular} \end{center} \end{description} \cfuncref{PL_open_query}{} can return the query identifier \const{0} if there is not enough space on the environment stack (and makes the exception available through \exam{\cfuncref{PL_exception}{0}}). This function succeeds, even if the referenced predicate is not defined. In this case, running the query using \cfuncref{PL_next_solution}{} may return an existence_error. See \cfuncref{PL_exception}{}. The example below opens a query to the predicate \nopredref{is_a}{2} to find the ancestor of `me'. The reference to the predicate is valid for the duration of the process or until \cfuncref{PL_cleanup}{} is called (see \cfuncref{PL_predicate}{} for details) and may be cached by the client. \begin{code} char * ancestor(const char *me) { term_t a0 = PL_new_term_refs(2); static predicate_t p; if ( !p ) p = PL_predicate("is_a", 2, "database"); PL_put_atom_chars(a0, me); PL_open_query(NULL, PL_Q_PASS_EXCEPTION, p, a0); ... } \end{code} \noindent \cfunction{int}{PL_next_solution}{qid_t qid} Generate the first (next) solution for the given query. The return value is \const{TRUE} if a solution was found, or \const{FALSE} to indicate the query could not be proven. This function may be called repeatedly until it fails to generate all solutions to the query. The return value \const{PL_S_NOT_INNER} is returned if \arg{qid} is not the innermost query. If the \cfuncref{PL_open_query}{} had the flag \const{PL_Q_EXT_STATUS}, there are additional return values (see \secref{foreign-yield}). \cfunction{int}{PL_cut_query}{qid_t qid} Discards the query, but does not delete any of the data created by the query. It just invalidates \arg{qid}, allowing for a new call to \cfuncref{PL_open_query}{} in this context. \cfuncref{PL_cut_query}{} may invoke cleanup handlers (see \index{setup_call_cleanup/3}\predref{setup_call_cleanup}{3}) and therefore may experience exceptions. If an exception occurs the return value is \const{FALSE} and the exception is accessible through \exam{\cfuncref{PL_exception}{0}}. An example of a handler that can trigger an exception in \cfuncref{PL_cut_query}{} is: \begin{code} test_setup_call_cleanup(X) :- setup_call_cleanup( true, between(1, 5, X), throw(error)). \end{code} \noindent where \cfuncref{PL_next_solution}{} returns \const{TRUE} on the first result and the \exam{throw(error)} will only run when \cfuncref{PL_cut_query}{} or \cfuncref{PL_close_query}{} is run. On the other hand, if the goal in \index{setup_call_cleanup/3}\predref{setup_call_cleanup}{3} has completed (failure, exception, determinitic success), the cleanup handler will have done its work before control gets back to Prolog and therefore \cfuncref{PL_next_solution}{} will have generated the exception. The return value \const{PL_S_NOT_INNER} is returned if \arg{qid} is not the innermost query. \cfunction{int}{PL_close_query}{qid_t qid} As \cfuncref{PL_cut_query}{}, but all data and bindings created by the query are destroyed as if the query is called as \verb$\+ \+ Goal$. This reduces the need for garbage collection, but also rewinds side effects such as setting global variables using \index{b_setval/2}\predref{b_setval}{2}. The return value \const{PL_S_NOT_INNER} is returned if \arg{qid} is not the innermost query. \cfunction{qid_t}{PL_current_query}{void} Returns the query id of the current query or \const{0} if the current thread is not executing any queries. \cfunction{PL_engine_t}{PL_query_engine}{qid_t qid} Return the engine to which \arg{qid} belongs. Note that interacting with a query or the Prolog terms associated with a query requires the engine to be \jargon{current}. See \cfuncref{PL_set_engine}{}. \cfunction{int}{PL_call_predicate}{module_t m, int flags, predicate_t pred, term_t +t0} Shorthand for \cfuncref{PL_open_query}{}, \cfuncref{PL_next_solution}{}, \cfuncref{PL_cut_query}{}, generating a single solution. The arguments are the same as for \cfuncref{PL_open_query}{}, the return value is the same as \cfuncref{PL_next_solution}{}. \cfunction{int}{PL_call}{term_t t, module_t m} Call term \arg{t} just like the Prolog predicate \index{once/1}\predref{once}{1}. \arg{t} is called in the module \arg{m}, or in the context module if \arg{m} == NULL. Returns \const{TRUE} if the call succeeds, \const{FALSE} otherwise. If the goal raises an exception the return value is \const{FALSE} and the exception term is available using \cfuncref{PL_exception}{0}.\footnote{Up to version 9.1.11 the debugger was started and the exception was not propagated.} \Figref{calling} shows an example to obtain the number of defined atoms. \end{description} \subsection{Discarding Data} \label{sec:foreign-discard-term-t} The Prolog data created and term references needed to set up the call and/or analyse the result can in most cases be discarded right after the call. \cfuncref{PL_close_query}{} allows for destroying the data, while leaving the term references. The calls below may be used to destroy term references and data. See \figref{calling} for an example. \begin{description} \cfunction{fid_t}{PL_open_foreign_frame}{} Create a foreign frame, holding a mark that allows the system to undo bindings and destroy data created after it, as well as providing the environment for creating term references. This function is called by the kernel before calling a foreign predicate. Returns \exam{(fid_t)0} on failure. Failure is either lack of space on the stacks, in which case a resource exception is scheduled or atom-gc being in progress in the current thread, in which case no exception is scheduled. The latter is an exceptional case that prevents doing a callback on Prolog from \jargon{blob release handlers}.\footnote{Such a callback would \jargon{deadlock} if the callback creates new atoms or requires stack shifts or garbage collection.} \cfunction{void}{PL_close_foreign_frame}{fid_t id} Discard all term references created after the frame was opened. All other Prolog data is retained. This function is called by the kernel whenever a foreign function returns control back to Prolog. \cfunction{void}{PL_discard_foreign_frame}{fid_t id} Same as \cfuncref{PL_close_foreign_frame}{}, but also undo all bindings made since the open and destroy all Prolog data. \cfunction{void}{PL_rewind_foreign_frame}{fid_t id} Undo all bindings and discard all term references created since the frame was created, but do not pop the frame. That is, the same frame can be rewound multiple times, and must eventually be closed or discarded. \end{description} It is obligatory to call either of the two closing functions to discard a foreign frame. Foreign frames may be nested. \begin{figure} \begin{code} int count_atoms() { fid_t fid = PL_open_foreign_frame(); term_t goal = PL_new_term_ref(); term_t a1 = PL_new_term_ref(); term_t a2 = PL_new_term_ref(); functor_t s2 = PL_new_functor(PL_new_atom("statistics"), 2); int atoms; PL_put_atom_chars(a1, "atoms"); PL_cons_functor(goal, s2, a1, a2); PL_call(goal, NULL); /* call it in current module */ PL_get_integer(a2, &atoms); PL_discard_foreign_frame(fid); return atoms; } \end{code} \noindent \caption{Calling Prolog} \label{fig:calling} \end{figure} \subsection{String buffering} \label{sec:foreign-strings} Many of the functions of the foreign language interface involve strings. Some of these strings point into static memory like those associated with atoms. These strings are valid as long as the atom is protected against atom garbage collection, which generally implies the atom must be locked using \cfuncref{PL_register_atom}{} or be part of an accessible term. Other strings are more volatile. Several functions provide a BUF_* flag that can be set to either \const{BUF_STACK} (default) or \const{BUF_MALLOC}. Strings returned by a function accepting \const{BUF_MALLOC} \textbf{must} be freed using \cfuncref{PL_free}{}. Strings returned using \const{BUF_STACK} are pushed on a stack that is cleared when a foreign predicate returns control back to Prolog. More fine grained control may be needed if functions that return strings are called outside the context of a foreign predicate or a foreign predicate creates many strings during its execution. Temporary strings are scoped using these macros: \begin{description} \cmacro{void}{PL_STRINGS_MARK}{} \nodescription \cmacro{void}{PL_STRINGS_RELEASE}{} These macros must be paired and create a C \jargon{block} (\{...\}). Any string created using \const{BUF_STACK} after \cfuncref{PL_STRINGS_MARK}{} is released by the corresponding \cfuncref{PL_STRINGS_RELEASE}{}. These macros should be used like below. Note that strings returned by any of the Prolog functions between this pair may be invalidated. \begin{code} ... PL_STRINGS_MARK(); PL_STRINGS_RELEASE(); ... \end{code} \noindent \end{description} The Prolog flag \prologflag{string_stack_tripwire} may be used to set a \jargon{tripwire} to help finding places where scoping strings may help reducing resources. \subsection{Foreign Code and Modules} \label{sec:foreign-modules} Modules are identified via a unique handle. The following functions are available to query and manipulate modules. \begin{description} \cfunction{module_t}{PL_context}{} Return the module identifier of the context module of the currently active foreign predicate. If there is no currently active predicate it returns a handle to the \const{user} module. \cfunction{int}{PL_strip_module}{term_t +raw, module_t *m, term_t -plain} Utility function. If \arg{raw} is a term, possibly holding the module construct \mbox{\bnfmeta{module}{\tt :}\bnfmeta{rest}}, this function will make \arg{plain} a reference to \bnfmeta{rest} and fill \arg{module *} with \bnfmeta{module}. For further nested module constructs the innermost module is returned via \arg{module *}. If \arg{raw} is not a module construct, \arg{raw} will simply be put in \arg{plain}. The value pointed to by \arg{m} must be initialized before calling \cfuncref{PL_strip_module}{}, either to the default module or to \const{NULL}. A \const{NULL} value is replaced by the current context module if \arg{raw} carries no module. The following example shows how to obtain the plain term and module if the default module is the user module: \begin{code} { module m = PL_new_module(PL_new_atom("user")); term_t plain = PL_new_term_ref(); PL_strip_module(term, &m, plain); ... } \end{code} \noindent Returns \const{TRUE} on success and \const{FALSE} on error, leaving an exception. Currently the only exception condition is \arg{raw} to be a cyclic term. \cfunction{atom_t}{PL_module_name}{module_t module} Return the name of \arg{module} as an atom. \cfunction{module_t}{PL_new_module}{atom_t name} Find an existing module or create a new module with the name \arg{name}. Currently aborts the process with a \jargon{fatal error} on failure. Future versions may raise a resource exception and return \exam{(module_t)0}. \end{description} \subsection{Prolog exceptions in foreign code} \label{sec:foreign-exceptions} This section discusses \cfuncref{PL_exception}{} and \cfuncref{PL_raise_exception}{}, the interface functions to detect and generate Prolog exceptions from C code. \cfuncref{PL_raise_exception}{} from the C interface registers the exception term and returns \const{FALSE}. If a foreign predicate returns \const{FALSE}, while an exception term is registered, a Prolog exception will be raised by the virtual machine. This implies for a foreign function that implements a predicate and wishes to raise an exception, the function must call \cfuncref{PL_raise_exception}{}, perform any necessary cleanup, and return the return code of \cfuncref{PL_raise_exception}{} or explicitly \const{FALSE}. Calling \cfuncref{PL_raise_exception}{} outside the context of a function implementing a foreign predicate results in undefined behaviour. Note that many of the C API functions may call \cfuncref{PL_raise_exception}{} and return \const{FALSE}. The user must test for this, cleanup, and make the foreign function return \const{FALSE}. \cfuncref{PL_exception}{} may be used to inspect the currently registered exception. It is normally called after a call to \cfuncref{PL_next_solution}{} returns \const{FALSE}, and returns a term reference to an exception term if an exception is pending, and \exam{(term_t)0} otherwise. It may also be called after, e.g., \cfuncref{PL_unify}{} to distinguish a normal failing unification from a unification that raised an resource error exception. \cfuncref{PL_exception}{} must only be called after a function such as \cfuncref{PL_next_solution}{} or \cfuncref{PL_unify}{} returns failure; if called elsewhere, the return value is undefined. If a C function implementing a predicate that calls Prolog should use \cfuncref{PL_open_query}{} with the flag \const{PL_Q_PASS_EXCEPTION} and make the function return FALSE if \cfuncref{PL_next_solution}{} returns \const{FALSE} and \cfuncref{PL_exception}{} indicates an exception is pending. Both for C functions implementing a predicate and when Prolog is called while the main control of the process is in C, user code should always check for exceptions. As explained above, C functions implementing a predicate should normally cleanup and return with \const{FALSE}. If the C function whishes to continue it may call \cfuncref{PL_clear_exception}{}. Note that this may cause any exception to be ignored, including \emph{time outs} and \emph{abort}. Typically the user should check the exception details before ignoring an exception (using \exam{\cfuncref{PL_exception}{0}} or \exam{\cfuncref{PL_exception}{qid}} as appropriate). If the C code does not implement a predicate it normally prints the exception and calls \cfuncref{PL_clear_exception}{} to discard it. Exceptions may be printed by calling \index{print_message/2}\predref{print_message}{2} through the C interface. \begin{description} \cfunction{int}{PL_raise_exception}{term_t exception} Generate an exception (as \index{throw/1}\predref{throw}{1}) and return \const{FALSE}. If there is already a pending exception, the most urgent exception is kept; and if both are of the same urgency, the new exception is kept. Urgency of exceptions is defined as \begin{enumerate} \item abort (\verb|'$aborted'|). \item \const{time_limit_exceeded} (see \index{call_with_time_limit/2}\predref{call_with_time_limit}{2}). \item \const{resource_error} exceptions. \item Other \term{error}{Formal, ImplDef} exceptions. \item Other exceptions. \end{enumerate} This function is rarely used directly. Instead, errors are typically raised using the functions in \secref{cerror} or the C api functions that end in \exam{_ex} such as \cfuncref{PL_get_atom_ex}{}. Below we give an example returning an exception from a foreign predicate the verbose way. Note that the exception is raised in a sequence of actions connected using \verb$&&$. This ensures that a proper exception is raised should any of the calls used to build or raise the exception themselves raise an exception. In this simple case \cfuncref{PL_new_term_ref}{} is guaranteed to succeed because the system guarantees at least 10 available term references before entering the foreign predicate. \cfuncref{PL_unify_term}{} however may raise a resource exception for the global stack. \begin{code} foreign_t pl_hello(term_t to) { char *s; if ( PL_get_atom_chars(to, &s) ) { Sprintf("Hello \"%s\"\n", s); return TRUE; } else { term_t except; return ( (except=PL_new_term_ref()) && PL_unify_term(except, PL_FUNCTOR_CHARS, "type_error", 2, PL_CHARS, "atom", PL_TERM, to) && PL_raise_exception(except) ); } } \end{code} \noindent For reference, the preferred implementation of the above is below. The \const{CVT_EXCEPTION} tells the system to generate an exception if the conversion fails. The other \const{CVT_} flags define the admissible types and \const{REP_MB} requests the string to be provided in the current \jargon{locale} representation. This implies that Unicode text is printed correctly if the current environment can represent it. If not, a \const{representation_error} is raised. \begin{code} foreign_t pl_hello(term_t to) { char *s; if ( PL_get_chars(to, &s, CVT_ATOM|CVT_STRING|CVT_EXCEPTION|REP_MB) ) { Sprintf("Hello \"%s\"\n", s); return TRUE; } return FALSE; } \end{code} \noindent \cfunction{int}{PL_throw}{term_t exception} Similar to \cfuncref{PL_raise_exception}{}, but returns using the C longjmp() function to the innermost \cfuncref{PL_next_solution}{}. This function is deprecated as it does not provide the opportunity to cleanup. \cfunction{term_t}{PL_exception}{qid_t qid} Return the \jargon{pending exception}. Exceptions may be raised by most of the API calls described in this chapter, a common possibility being \const{resource_error} exceptions. Some return \const{type_error} or \const{domain_error} exceptions. A call to Prolog using \cfuncref{PL_next_solution}{} may return any exception, including those thrown by explicit calls to \index{throw/1}\predref{throw}{1}. If no exception is pending this function returns \exam{(term_t)0}. Normally \arg{qid} should be \const{0}. An explicit \arg{qid} must be used after a call to \cfuncref{PL_next_solution}{} that returns \const{FALSE} when the query was created using the \const{PL_Q_PASS_EXCEPTION} flag (see \cfuncref{PL_open_query}{}). Note that an API may only raise an exception when it fails; if the API call succeeds, the result of \exam{\cfuncref{PL_exception}{0}} will be 0.\footnote{Provided no exception was pending before calling the API function. As clients must deal with exceptions immediately after an API call raises one, this can not happen in a well behaved client.} The implementation of a foreign predicate should normally cleanup and return \const{FALSE} after an exception is raised (and typically also after an API call failed for logical reasons; see \cfuncref{PL_unify}{} for an elaboration on this topic). If the call to Prolog is not the implementation of a foreign predicate, e.g., when the overall process control is in some other language, exceptions may be printed by calling \index{print_message/2}\predref{print_message}{2} and should be discarded by calling \cfuncref{PL_clear_exception}{}. \cfunction{void}{PL_clear_exception}{void} Tells Prolog that the encountered exception must be ignored. This function must be called if control remains in C after a previous API call fails with an exception.\footnote{This feature is non-portable. Other Prolog systems (e.g., YAP) have no facilities to ignore raised exceptions, and the design of YAP's exception handling does not support such a facility.} If there is no pending exception, \cfuncref{PL_clear_exception}{} does nothing. \end{description} \subsection{Catching Signals (Software Interrupts)} \label{sec:csignal} SWI-Prolog offers both a C and Prolog interface to deal with software interrupts (signals). The Prolog mapping is defined in \secref{signal}. This subsection deals with handling signals from C. If a signal is not used by Prolog and the handler does not call Prolog in any way, the native signal interface routines may be used. Any handler that wishes to call one of the Prolog interface functions should call \cfuncref{PL_sigaction}{} to install the handler. \cfuncref{PL_signal}{} provides a deprecated interface that is notably not capable of properly restoring the old signal status if the signal was previously handled by Prolog. \begin{description} \cfunction{int}{PL_sigaction}{int sig, pl_sigaction_t *act, pl_sigaction_t *oldact} Install or query the status for signal \arg{sig}. The signal is an integer between 1 and 64, where the where the signals up to 32 are mapped to OS signals and signals above that are handled by Prolog's synchronous signal handling. The \ctype{pl_sigaction_t} is a struct with the following definition: \begin{code} typedef struct pl_sigaction { void (*sa_cfunction)(int); /* traditional C function */ predicate_t sa_predicate; /* call a predicate */ int sa_flags; /* additional flags */ } pl_sigaction_t; \end{code} \noindent The \const{sa_flags} is a bitwise or of \const{PLSIG_THROW}, \const{PLSIG_SYNC} and \const{PLSIG_NOFRAME}. Signal handling is enabled if \const{PLSIG_THROW} is provided, \const{sa_cfunction} or \const{sa_predicate} is provided. \const{sa_predicate} is a predicate handle for a predicate with arity~1. If no action is provided the signal handling for this signal is restored to the default before \cfuncref{PL_initialise}{} was called. Finally, 0 (zero) may be passed for \arg{sig}. In that case the system allocates a free signal in the \textit{Prolog range} (32\ldots{}64). Such signal handler are activated using \cfuncref{PL_thread_raise}{}. \cfunction{void (*)()}{PL_signal}{sig, func} This function is equivalent to the BSD-Unix signal() function, regardless of the platform used. The signal handler is blocked while the signal routine is active, and automatically reactivated after the handler returns. After a signal handler is registered using this function, the native signal interface redirects the signal to a generic signal handler inside SWI-Prolog. This generic handler validates the environment, creates a suitable environment for calling the interface functions described in this chapter and finally calls the registered user-handler. By default, signals are handled asynchronously (i.e., at the time they arrive). It is inherently dangerous to call extensive code fragments, and especially exception related code from asynchronous handlers. The interface allows for \jargon{synchronous} handling of signals. In this case the native OS handler just schedules the signal using \cfuncref{PL_raise}{}, which is checked by \cfuncref{PL_handle_signals}{} at the call- and redo-port. This behaviour is realised by \emph{or}-ing \arg{sig} with the constant \const{PL_SIGSYNC}.% \footnote{A better default would be to use synchronous handling, but this interface preserves backward compatibility.} Signal handling routines may raise exceptions using \cfuncref{PL_raise_exception}{}. The use of \cfuncref{PL_throw}{} is not safe. If a synchronous handler raises an exception, the exception is delayed to the next call to \cfuncref{PL_handle_signals}{}; \cfunction{int}{PL_raise}{int sig} Register \arg{sig} for \emph{synchronous} handling by Prolog. Synchronous signals are handled at the call-port or if foreign code calls \cfuncref{PL_handle_signals}{}. See also \index{thread_signal/2}\predref{thread_signal}{2}. \cfunction{int}{PL_handle_signals}{void} Handle any signals pending from \cfuncref{PL_raise}{}. \cfuncref{PL_handle_signals}{} is called at each pass through the call- and redo-port at a safe point. Exceptions raised by the handler using \cfuncref{PL_raise_exception}{} are properly passed to the environment. The user may call this function inside long-running foreign functions to handle scheduled interrupts. This routine returns the number of signals handled. If a handler raises an exception, the return value is -1 and the calling routine should return with \const{FALSE} as soon as possible. \cfunction{int}{PL_get_signum_ex}{term_t t, int *sig} Extract a signal specification from a Prolog term and store as an integer signal number in \arg{sig}. The specification is an integer, a lowercase signal name without \const{SIG} or the full signal name. These refer to the same: \verb$9$, \verb$kill$ and \verb$SIGKILL$. Leaves a typed, domain or instantiation error if the conversion fails. \end{description} \subsection{Miscellaneous} \label{sec:foreign-misc} \subsubsection{Term Comparison} \label{sec:foreign-compare} \begin{description} \cfunction{int}{PL_compare}{term_t t1, term_t t2} Compares two terms using the standard order of terms and returns -1, 0 or 1. See also \index{compare/3}\predref{compare}{3}. \cfunction{int}{PL_same_compound}{term_t t1, term_t t2} Yields \const{TRUE} if \arg{t1} and \arg{t2} refer to physically the same compound term and \const{FALSE} otherwise. \end{description} \subsubsection{Recorded database} \label{sec:foreign-recorded} In some applications it is useful to store and retrieve Prolog terms from C code. For example, the XPCE graphical environment does this for storing arbitrary Prolog data as slot-data of XPCE objects. Please note that the returned handles have no meaning at the Prolog level and the recorded terms are not visible from Prolog. The functions \cfuncref{PL_recorded}{} and \cfuncref{PL_erase}{} are the only functions that can operate on the stored term. Two groups of functions are provided. The first group (\cfuncref{PL_record}{} and friends) store Prolog terms on the Prolog heap for retrieval during the same session. These functions are also used by \index{recorda/3}\predref{recorda}{3} and friends. The recorded database may be used to communicate Prolog terms between threads. \begin{description} \cfunction{record_t}{PL_record}{term_t +t} Record the term \arg{t} into the Prolog database as \index{recorda/3}\predref{recorda}{3} and return an opaque handle to the term. The returned handle remains valid until \cfuncref{PL_erase}{} is called on it. \cfuncref{PL_recorded}{} is used to copy recorded terms back to the Prolog stack. Currently aborts the process with a \jargon{fatal error} on failure. Future versions may raise a resource exception and return \exam{(record_t)0}. \cfunction{record_t}{PL_duplicate_record}{record_t record} Return a duplicate of \arg{record}. As records are read-only objects this function merely increments the records reference count. Returns \exam{(record_t)0} if the \arg{record} is an \jargon{external record} (see \cfuncref{PL_record_external}{}). \cfunction{int}{PL_recorded}{record_t record, term_t -t} Copy a recorded term back to the Prolog stack. The same record may be used to copy multiple instances at any time to the Prolog stack. Returns \const{TRUE} on success, and \const{FALSE} if there is not enough space on the stack to accommodate the term. See also \cfuncref{PL_record}{} and \cfuncref{PL_erase}{}. \cfunction{void}{PL_erase}{record_t record} Remove the recorded term from the Prolog database, reclaiming all associated memory resources. \end{description} The second group (headed by \cfuncref{PL_record_external}{}) provides the same functionality, but the returned data has properties that enable storing the data on an external device. It has been designed for fast and compact storage of Prolog terms in an external database. Here are the main features: \begin{itemlist} \item [Independent of session] Records can be communicated to another Prolog session and made visible using \cfuncref{PL_recorded_external}{}. \item [Binary] The representation is binary for maximum performance. The returned data may contain zero bytes. \item [Byte-order independent] The representation can be transferred between machines with different byte order. \item [No alignment restrictions] There are no memory alignment restrictions and copies of the record can thus be moved freely. For example, it is possible to use this representation to exchange terms using shared memory between different Prolog processes. \item [Compact] It is assumed that a smaller memory footprint will eventually outperform slightly faster representations. \item [Stable] The format is designed for future enhancements without breaking compatibility with older records. \end{itemlist} \begin{description} \cfunction{char *}{PL_record_external}{term_t +t, size_t *len} Record the term \arg{t} into the Prolog database as \index{recorda/3}\predref{recorda}{3} and return an opaque handle to the term. The returned handle remains valid until \cfuncref{PL_erase_external}{} is called on it. Currently aborts the process with a \jargon{fatal error} on failure. Future versions may raise a resource exception and return \exam{(char*)0}. It is allowed to copy the data and use \cfuncref{PL_recorded_external}{} on the copy. The user is responsible for the memory management of the copy. After copying, the original may be discarded using \cfuncref{PL_erase_external}{}. \cfuncref{PL_record_external}{} will fail if the term contains \jargon{blobs} that cannot be serialized, such as streams. \cfuncref{PL_recorded_external}{} is used to copy such recorded terms back to the Prolog stack. \cfunction{int}{PL_recorded_external}{const char *record, term_t -t} Copy a recorded term back to the Prolog stack. The same record may be used to copy multiple instances at any time to the Prolog stack. See also \cfuncref{PL_record_external}{} and \cfuncref{PL_erase_external}{}. \cfunction{int}{PL_erase_external}{char *record} Remove the recorded term from the Prolog database, reclaiming all associated memory resources. \end{description} \subsubsection{Database} \label{sec:foreign-db} \begin{description} \cfunction{int}{PL_assert}{term_t t, module_t m, int flags} Provides direct access to \index{asserta/1}\predref{asserta}{1} and \index{assertz/1}\predref{assertz}{1} by asserting \arg{t} into the database in the module \arg{m}. Defined flags are: \begin{description} \termitem{PL_ASSERTZ}{} Add the new clause as last. Calls \index{assertz/1}\predref{assertz}{1}. This macros is defined as 0 and thus the default. \termitem{PL_ASSERTA}{} Add the new clause as first. Calls \index{asserta/1}\predref{asserta}{1}. \termitem{PL_CREATE_THREAD_LOCAL}{} If the predicate is not defined, create it as thread-local. See \index{thread_local/1}\predref{thread_local}{1}. \termitem{PL_CREATE_INCREMENTAL}{} If the predicate is not defined, create it as \jargon{incremental} see \index{table/1}\predref{table}{1} and \secref{tabling-incremental}. \end{description} On success this function returns \const{TRUE}. On failure \const{FALSE} is returned and an exception is left in the environment that describes the reason of failure. See \cfuncref{PL_exception}{}. This predicate bypasses creating a Prolog callback environment and is faster than setting up a call to \index{assertz/1}\predref{assertz}{1}. It may be used together with \cfuncref{PL_chars_to_term}{}, but the typical use case will create a number of clauses for the same predicate. The fastest way to achieve this is by creating a term that represents the invariable structure of the desired clauses using variables for the variable sub terms. Now we can loop over the data, binding the variables, asserting the term and undoing the bindings. Below is an example loading words from a file that contains a word per line. \begin{code} #include #include #include #define MAXWLEN 256 static foreign_t load_words(term_t name) { char *fn; if ( PL_get_file_name(name, &fn, PL_FILE_READ) ) { FILE *fd = fopen(fn, "r"); char word[MAXWLEN]; module_t m = PL_new_module(PL_new_atom("words")); term_t cl = PL_new_term_ref(); term_t w = PL_new_term_ref(); fid_t fid; if ( !PL_unify_term(cl, PL_FUNCTOR_CHARS, "word", 1, PL_TERM, w) ) return FALSE; if ( (fid = PL_open_foreign_frame()) ) { while(fgets(word, sizeof word, fd)) { size_t len; if ( (len=strlen(word)) ) { word[len-1] = '\0'; if ( !PL_unify_chars(w, PL_ATOM|REP_MB, (size_t)-1, word) || !PL_assert(cl, m, 0) ) return FALSE; PL_rewind_foreign_frame(fid); } } PL_close_foreign_frame(fid); } fclose(fd); return TRUE; } return FALSE; } install_t install(void) { PL_register_foreign("load_words", 1, load_words, 0); } \end{code} \noindent \end{description} \subsubsection{Getting file names} \label{sec:cfilenames} The function \cfuncref{PL_get_file_name}{} provides access to Prolog filenames and its file-search mechanism described with \index{absolute_file_name/3}\predref{absolute_file_name}{3}. Its existence is motivated to realise a uniform interface to deal with file properties, search, naming conventions, etc., from foreign code. \begin{description} \cfunction{int}{PL_get_file_name}{term_t spec, char **name, int flags} Translate a Prolog term into a file name. The name is stored in the buffer stack described with the \cfuncref{PL_get_chars}{} option \const{BUF_STACK}. Conversion from the internal UNICODE encoding is done using standard C library functions. \arg{flags} is a bit-mask controlling the conversion process. Options are: \begin{description} \definition{\const{PL_FILE_ABSOLUTE}} Return an absolute path to the requested file. \definition{\const{PL_FILE_OSPATH}} Return the name using the hosting OS conventions. On MS-Windows, \chr{\Sneg} is used to separate directories rather than the canonical \chr{\Sdiv}. \definition{\const{PL_FILE_SEARCH}} Invoke \index{absolute_file_name/3}\predref{absolute_file_name}{3}. This implies rules from \index{file_search_path/2}\predref{file_search_path}{2} are used. \definition{\const{PL_FILE_EXIST}} Demand the path to refer to an existing entity. \definition{\const{PL_FILE_READ}} Demand read-access on the result. \definition{\const{PL_FILE_WRITE}} Demand write-access on the result. \definition{\const{PL_FILE_EXECUTE}} Demand execute-access on the result. \definition{\const{PL_FILE_NOERRORS}} Do not raise any exceptions. \end{description} \cfunction{int}{PL_get_file_nameW}{term_t spec, wchar_t **name, int flags} Same as \cfuncref{PL_get_file_name}{}, but returns the filename as a wide-character string. This is intended for Windows to access the Unicode version of the Win32 API. Note that the flag \const{PL_FILE_OSPATH} must be provided to fetch a filename in OS native (e.g., \verb$C:\x\y$) notation. \end{description} \subsubsection{Dealing with Prolog flags from C} \label{sec:cprologflags} Foreign code can set or create Prolog flags using \cfuncref{PL_set_prolog_flag}{}. See \index{set_prolog_flag/2}\predref{set_prolog_flag}{2} and \index{create_prolog_flag/3}\predref{create_prolog_flag}{3}. To retrieve the value of a flag you can use \cfuncref{PL_current_prolog_flag}{}. \begin{description} \cfunction{int}{PL_set_prolog_flag}{const char *name, int type, ...} Set/create a Prolog flag from C. \arg{name} is the name of the affected flag. \arg{type} is one of the values below, which also dictates the type of the final argument. The function returns \const{TRUE} on success and \const{FALSE} on failure. This function can be called \emph{before} \cfuncref{PL_initialise}{}, making the flag available to the Prolog startup code. \begin{description} \definition{\const{PL_BOOL}} Create a boolean (\const{true} or \const{false}) flag. The argument must be an \ctype{int}. \definition{\const{PL_ATOM}} Create a flag with an atom as value. The argument must be of type \ctype{const char *}. \definition{\const{PL_INTEGER}} Create a flag with an integer as value. The argument must be of type \ctype{intptr_t *}. \end{description} \end{description} \begin{description} \cfunction{int}{PL_current_prolog_flag}{atom_t name, int type, void *value} Retrieve the value of a Prolog flag from C. \arg{name} is the name of the flag as an \const{atom_t} (see \index{current_prolog_flag/2}\predref{current_prolog_flag}{2}). \arg{type} specifies the kind of value to be retrieved, it is one of the values below. \arg{value} is a pointer to a location where to store the value. The user is responsible for making sure this memory location is of the appropriate size/type (see the returned types below to determine the size/type). The function returns \const{TRUE} on success and \const{FALSE} on failure. \begin{description} \definition{\const{PL_ATOM}} Retrieve a flag whose value is an \const{atom}. The returned value is an atom handle of type \ctype{atom_t}. \definition{\const{PL_INTEGER}} Retrieve a flag whose value is an \const{integer}. The returned value is an integer of type \ctype{int64_t}. \definition{\const{PL_FLOAT}} Retrieve a flag whose value is a \const{float}. The returned value is a floating point number of type \ctype{double}. \definition{\const{PL_TERM}} Retrieve a flag whose value is a \const{term}. The returned value is a term handle of type \ctype{term_t}. \end{description} \end{description} \subsection{Errors and warnings} \label{sec:foreign-print-warning} \cfuncref{PL_warning}{} prints a standard Prolog warning message to the standard error (\const{user_error}) stream. Please note that new code should consider using \cfuncref{PL_raise_exception}{} to raise a Prolog exception. See also \secref{exception}. \begin{description} \cfunction{int}{PL_warning}{format, a1, \ldots} Print an error message starting with `{\tt [WARNING: }', followed by the output from \arg{format}, followed by a `\chr{]}' and a newline. Then start the tracer. \arg{format} and the arguments are the same as for \manref{printf}{2}. Always returns \const{FALSE}. \end{description} \subsection{Environment Control from Foreign Code} \label{sec:foreign-control-prolog} \begin{description} \cfunction{int}{PL_action}{int, ...} Perform some action on the Prolog system. \arg{int} describes the action. Remaining arguments depend on the requested action. The actions are listed below: \begin{description} \termitem{PL_ACTION_TRACE}{} Start Prolog tracer (\index{trace/0}\predref{trace}{0}). Requires no arguments. \termitem{PL_ACTION_DEBUG}{} Switch on Prolog debug mode (\index{debug/0}\predref{debug}{0}). Requires no arguments. \termitem{PL_ACTION_BACKTRACE}{} Print backtrace on current output stream. The argument (an \ctype{int}) is the number of frames printed. \termitem{PL_ACTION_HALT}{} Halt Prolog execution. This action should be called rather than Unix exit() to give Prolog the opportunity to clean up. This call does not return. The argument (an \ctype{int}) is the exit code. See \index{halt/1}\predref{halt}{1}. \termitem{PL_ACTION_ABORT}{} Generate a Prolog abort (\index{abort/0}\predref{abort}{0}). This call does not return. Requires no arguments. \termitem{PL_ACTION_BREAK}{} Create a standard Prolog break environment (\index{break/0}\predref{break}{0}). Returns after the user types the end-of-file character. Requires no arguments. \termitem{PL_ACTION_GUIAPP}{} Windows: Used to indicate to the kernel that the application is a GUI application if the argument is not 0, and a console application if the argument is 0. If a fatal error occurs, the system uses a windows messagebox to report this on a GUI application, and otherwise simply prints the error and exits. \termitem{PL_ACTION_TRADITIONAL}{} Same effect as using \cmdlineoption{--traditional}. Must be called \emph{before} \cfuncref{PL_initialise}{}. \termitem{PL_ACTION_WRITE}{} Write the argument, a \ctype{char *} to the current output stream. \termitem{PL_ACTION_FLUSH}{} Flush the current output stream. Requires no arguments. \termitem{PL_ACTION_ATTACH_CONSOLE}{} Attach a console to a thread if it does not have one. See \index{attach_console/0}\predref{attach_console}{0}. \termitem{PL_GMP_SET_ALLOC_FUNCTIONS}{} Takes an integer argument. If \const{TRUE}, the GMP allocations are immediately bound to the Prolog functions. If \const{FALSE}, SWI-Prolog will never rebind the GMP allocation functions. See mp_set_memory_functions() in the GMP documentation. The action returns \const{FALSE} if there is no GMP support or GMP is already initialised. \end{description} \cfunction{unsigned int}{PL_version_info}{int key} Query version information. This function may be called before \cfuncref{PL_initialise}{}. If the key is unknown the function returns 0. See \secref{abi-versions} for a more in-depth discussion on binary compatibility. Versions upto SWI-Prolog 8.5.2 defined this function as \cfuncref{PL_version}{}. It was renamed to avoid a conflict with Perl affecting \href{https://github.com/salva/p5-Language-Prolog-Yaswi}{Yaswi}. \cfuncref{PL_version}{} is provided as a macro for compatibility. Defined keys are: \begin{description} \termitem{PL_VERSION_SYSTEM}{} SWI-Prolog version as $10,000 \times major + 100 \times minor + patch$. \termitem{PL_VERSION_FLI}{} Incremented if the foreign interface defined in this chapter changes in a way that breaks backward compatibility. \termitem{PL_VERSION_REC}{} Incremented if the binary representation of terms as used by \cfuncref{PL_record_external}{} and \index{fast_write/2}\predref{fast_write}{2} changes. \termitem{PL_VERSION_QLF}{} Incremented if the QLF file format changes. \termitem{PL_VERSION_QLF_LOAD}{} Represents the oldest loadable QLF file format version. \termitem{PL_VERSION_VM}{} A hash that represents the VM instructions and their arguments. \termitem{PL_VERSION_BUILT_IN}{} A hash that represents the names, arities and properties of all built-in predicates defined in C. If this function is called before \cfuncref{PL_initialise}{} it returns 0. \end{description} \end{description} \subsection{Querying Prolog} \label{sec:foreign-query} \begin{description} \cfunction{long}{PL_query}{int} Obtain status information on the Prolog system. The actual argument type depends on the information required. \arg{int} describes what information is wanted.% \footnote{Returning pointers and integers as a long is bad style. The signature of this function should be changed.} The options are given in \tabref{query}. \begin{table} \begin{quote}\begin{tabular}{|p{\tableft}|p{\linewidth-\tableft-2cm}|} \hline \const{PL_QUERY_ARGC} & Return an integer holding the number of arguments given to Prolog from Unix. \\ \const{PL_QUERY_ARGV} & Return a \ctype{char **} holding the argument vector given to Prolog from Unix. \\ \const{PL_QUERY_SYMBOLFILE} & Return a \ctype{char *} holding the current symbol file of the running process. \\ \const{PL_MAX_INTEGER} & Return a long, representing the maximal integer value represented by a Prolog integer. \\ \const{PL_MIN_INTEGER} & Return a long, representing the minimal integer value. \\ \const{PL_QUERY_VERSION} & Return a long, representing the version as $10,000 \times M + 100 \times m + p$, where $M$ is the major, $m$ the minor version number and $p$ the patch level. For example, \exam{20717} means \exam{2.7.17}. \\ \const{PL_QUERY_ENCODING} & Return the default stream encoding of Prolog (of type \ctype{IOENC}). \\ \const{PL_QUERY_USER_CPU} & Get amount of user CPU time of the process in milliseconds. \\ \hline \end{tabular}\end{quote} \caption{\cfuncref{PL_query}{} options} \label{tab:query} \end{table} \end{description} \subsection{Registering Foreign Predicates} \label{sec:foreign-register-predicate} \begin{description} \cfunction{int}{PL_register_foreign_in_module}{char *mod, char *name, int arity, foreign_t (*f)(), int flags, ...} Register the C function \arg{f} to implement a Prolog predicate. After this call returns successfully a predicate with name \arg{name} (a \ctype{char *}) and arity \arg{arity} (a C \ctype{int}) is created in module \arg{mod}. If \arg{mod} is \const{NULL}, the predicate is created in the module of the calling context, or if no context is present in the module \const{user}. When called in Prolog, Prolog will call \arg{function}. \arg{flags} form a bitwise \emph{or}'ed list of options for the installation. These are: \begin{tabular}{|p{\tableft}|p{\linewidth-\tableft-2cm}|} \hline \const{PL_FA_META} & Provide meta-predicate info (see below) \\ \const{PL_FA_TRANSPARENT} & Predicate is module transparent (deprecated) \\ \const{PL_FA_NONDETERMINISTIC} & Predicate is non-deterministic. See also \cfuncref{PL_retry}{}. \\ \const{PL_FA_NOTRACE} & Predicate cannot be seen in the tracer \\ \const{PL_FA_VARARGS} & Use alternative calling convention. \\ \hline \end{tabular} If \const{PL_FA_META} is provided, \cfuncref{PL_register_foreign_in_module}{} takes one extra argument. This argument is of type \ctype{const char*}. This string must be exactly as long as the number of arguments of the predicate and filled with characters from the set \verb$0-9:^-+?$. See \index{meta_predicate/1}\predref{meta_predicate}{1} for details. \const{PL_FA_TRANSPARENT} is implied if at least one meta-argument is provided (\verb$0-9:^$). Note that meta-arguments are \emph{not always} passed as \bnfmeta{module}:\bnfmeta{term}. Always use \cfuncref{PL_strip_module}{} to extract the module and plain term from a meta-argument.\footnote{It is encouraged to pass an additional \const{NULL} pointer for non-meta-predicates.} Predicates may be registered either before or after \cfuncref{PL_initialise}{}. When registered before initialisation the registration is recorded and executed after installing the system predicates and before loading the saved state. Default calling (i.e.\ without \const{PL_FA_VARARGS}) \arg{function} is passed the same number of \ctype{term_t} arguments as the arity of the predicate and, if the predicate is non-deterministic, an extra argument of type \ctype{control_t} (see \secref{foreignnondet}). If \const{PL_FA_VARARGS} is provided, \arg{function} is called with three arguments. The first argument is a \ctype{term_t} handle to the first argument. Further arguments can be reached by adding the offset (see also \cfuncref{PL_new_term_refs}{}). The second argument is the arity, which defines the number of valid term references in the argument vector. The last argument is used for non-deterministic calls. It is currently undocumented and should be defined of type \ctype{void*}. Here is an example: \begin{code} static foreign_t atom_checksum(term_t a0, int arity, void* context) { char *s; if ( PL_get_atom_chars(a0, &s) ) { int sum; for(sum=0; *s; s++) sum += *s&0xff; return PL_unify_integer(a0+1, sum&0xff); } return FALSE; } install_t install() { PL_register_foreign("atom_checksum", 2, atom_checksum, PL_FA_VARARGS); } \end{code} \noindent \cfunction{int}{PL_register_foreign}{const char *name, int arity, foreign_t (*function)(), int flags, ...} Same as \cfuncref{PL_register_foreign_in_module}{}, passing \const{NULL} for the \arg{module}. \cfunction{void}{PL_register_extensions_in_module}{const char *module, PL_extension *e} Register a series of predicates from an array of definitions of the type \ctype{PL_extension} in the given \arg{module}. If \arg{module} is \const{NULL}, the predicate is created in the module of the calling context, or if no context is present in the module \const{user}. The \ctype{PL_extension} type is defined as \begin{code} typedef struct PL_extension { char *predicate_name; /* Name of the predicate */ short arity; /* Arity of the predicate */ pl_function_t function; /* Implementing functions */ short flags; /* Or of PL_FA_... */ } PL_extension; \end{code} \noindent For details, see \cfuncref{PL_register_foreign_in_module}{}. Here is an example of its usage: \begin{code} static PL_extension predicates[] = { { "foo", 1, pl_foo, 0 }, { "bar", 2, pl_bar, PL_FA_NONDETERMINISTIC }, { NULL, 0, NULL, 0 } }; main(int argc, char **argv) { PL_register_extensions_in_module("user", predicates); if ( !PL_initialise(argc, argv) ) PL_halt(1); ... } \end{code} \noindent \cfunction{void}{PL_register_extensions}{ PL_extension *e} Same as \cfuncref{PL_register_extensions_in_module}{} using \const{NULL} for the \arg{module} argument. \end{description} \subsection{Foreign Code Hooks} \label{sec:foreign-hooks} For various specific applications some hooks are provided. \begin{description} \cfunction{PL_dispatch_hook_t}{PL_dispatch_hook}{PL_dispatch_hook_t} If this hook is not NULL, this function is called when reading from the terminal. It is supposed to dispatch events when SWI-Prolog is connected to a window environment. It can return two values: \const{PL_DISPATCH_INPUT} indicates Prolog input is available on file descriptor 0 or \const{PL_DISPATCH_TIMEOUT} to indicate a timeout. The old hook is returned. The type \ctype{PL_dispatch_hook_t} is defined as: \begin{code} typedef int (*PL_dispatch_hook_t)(void); \end{code} \noindent \cfunction{void}{PL_abort_hook}{PL_abort_hook_t} Install a hook when \index{abort/0}\predref{abort}{0} is executed. SWI-Prolog \index{abort/0}\predref{abort}{0} is implemented using C setjmp()/longjmp() construct. The hooks are executed in the reverse order of their registration after the longjmp() took place and before the Prolog top level is reinvoked. The type \ctype{PL_abort_hook_t} is defined as: \begin{code} typedef void (*PL_abort_hook_t)(void); \end{code} \noindent \cfunction{int}{PL_abort_unhook}{PL_abort_hook_t} Remove a hook installed with \cfuncref{PL_abort_hook}{}. Returns \const{FALSE} if no such hook is found, \const{TRUE} otherwise. \cfunction{void}{PL_on_halt}{int (*f)(int, void *), void *closure} Register the function \arg{f} to be called if SWI-Prolog is halted. The function is called with two arguments: the exit code of the process (0 if this cannot be determined) and the \arg{closure} argument passed to the \cfuncref{PL_on_halt}{} call. Handlers \emph{must} return 0. Other return values are reserved for future use. See also \index{at_halt/1}\predref{at_halt}{1}.\bug{Although both \cfuncref{PL_on_halt}{} and \index{at_halt/1}\predref{at_halt}{1} are called in FIFO order, \emph{all} \index{at_halt/1}\predref{at_halt}{1} handlers are called before \emph{all} \cfuncref{PL_on_halt}{} handlers.} These handlers are called \emph{before} system cleanup and can therefore access all normal Prolog resources. See also \cfuncref{PL_exit_hook}{}. \cfunction{void}{PL_exit_hook}{int (*f)(int, void *), void *closure} Similar to \cfuncref{PL_on_halt}{}, but the hooks are executed by \cfuncref{PL_halt}{} instead of \cfuncref{PL_cleanup}{} just before calling exit(). \cfunction{PL_agc_hook_t}{PL_agc_hook}{PL_agc_hook_t new} Register a hook with the atom-garbage collector (see \index{garbage_collect_atoms/0}\predref{garbage_collect_atoms}{0}) that is called on any atom that is reclaimed. The old hook is returned. If no hook is currently defined, \const{NULL} is returned. The argument of the called hook is the atom that is to be garbage collected. The return value is an \ctype{int}. If the return value is zero, the atom is {\bf not} reclaimed. The hook may invoke any Prolog predicate. The example below defines a foreign library for printing the garbage collected atoms for debugging purposes. \begin{code} #include #include static int atom_hook(atom_t a) { Sdprintf("AGC: deleting %s\n", PL_atom_chars(a)); return TRUE; } static PL_agc_hook_t old; install_t install() { old = PL_agc_hook(atom_hook); } install_t uninstall() { PL_agc_hook(old); } \end{code} \noindent \end{description} \subsection{Storing foreign data} \label{sec:foreigndata} When combining foreign code with Prolog, it can be necessary to make data represented in the foreign language available to Prolog. For example, to pass it to another foreign function. At the end of this section, there is a partial implementation of using foreign functions to manage bit-vectors. Another example is the SGML/XML library that manages a `parser' object, an object that represents the current state of the parser and that can be directed to perform actions such as parsing a document or make queries about the document content. This section provides some hints for handling foreign data in Prolog. There are four options for storing such data: \begin{itemlist} \item[Natural Prolog data] Uses the representation one would choose if no foreign interface was required. For example, a bitvector representing a list of small integers can be represented as a Prolog list of integers. \item[Opaque packed data on the stacks] It is possible to represent the raw binary representation of the foreign object as a Prolog string (see \secref{string}). Strings may be created from foreign data using \cfuncref{PL_put_string_nchars}{} and retrieved using \cfuncref{PL_get_string_chars}{}. It is good practice to wrap the string in a compound term with arity 1, so Prolog can identify the type. The hook \index{portray/1}\predref{portray}{1} rules may be used to streamline printing such terms during development. \item[Opaque packed data in a blob] Similar to the above solution, binary data can be stored in an atom. The blob interface (\secref{blob}) provides additional facilities to assign a type and hook-functions that act on creation and destruction of the underlying atom. \item[Natural foreign data, passed as a pointer] An alternative is to pass a pointer to the foreign data. Again, the pointer is often wrapped in a compound term. \end{itemlist} \noindent The choice may be guided using the following distinctions \begin{itemlist} \item[Is the data opaque to Prolog] With `opaque' data, we refer to data handled in foreign functions, passed around in Prolog, but where Prolog never examines the contents of the data itself. If the data is opaque to Prolog, the selection will be driven solely by simplicity of the interface and performance. \item[What is the lifetime of the data] With `lifetime' we refer to how it is decided that the object is (or can be) destroyed. We can distinguish three cases: \begin{enumerate} \item The object must be destroyed on backtracking and normal Prolog garbage collection (i.e., it acts as a normal Prolog term). In this case, representing the object as a Prolog string (second option above) is the only feasible solution. \item The data must survive Prolog backtracking. This leaves two options. One is to represent the object using a pointer and use explicit creation and destruction, making the programmer responsible. The alternative is to use the blob-interface, leaving destruction to the (atom) garbage collector. \item The data lives as during the lifetime of a foreign function that implements a predicate. If the predicate is deterministic, foreign automatic variables are suitable. If the predicate is non-deterministic, the data may be allocated using malloc() and a pointer may be passed. See \secref{foreignnondet}. \end{enumerate} \end{itemlist} \subsubsection{Examples for storing foreign data} \label{sec:foreign-store-data} In this section, we outline some examples, covering typical cases. In the first example, we will deal with extending Prolog's data representation with integer sets, represented as bit-vectors. Then, we discuss the outline of the DDE interface. \paragraph{Integer sets} with not-too-far-apart upper- and lower-bounds can be represented using bit-vectors. Common set operations, such as union, intersection, etc., are reduced to simple \emph{and}'ing and \emph{or}'ing the bit-vectors. This can be done using Prolog's unbounded integers. For really demanding applications, foreign representation will perform better, especially time-wise. Bit-vectors are naturally expressed using string objects. If the string is wrapped in \functor{bitvector}{1}, the lower-bound of the vector is 0 and the upper-bound is not defined; an implementation for getting and putting the sets as well as the union predicate for it is below. \begin{code} #include #define max(a, b) ((a) > (b) ? (a) : (b)) #define min(a, b) ((a) < (b) ? (a) : (b)) static functor_t FUNCTOR_bitvector1; static int get_bitvector(term_t in, int *len, unsigned char **data) { if ( PL_is_functor(in, FUNCTOR_bitvector1) ) { term_t a = PL_new_term_ref(); PL_get_arg(1, in, a); return PL_get_string(a, (char **)data, len); } PL_fail; } static int unify_bitvector(term_t out, int len, const unsigned char *data) { if ( PL_unify_functor(out, FUNCTOR_bitvector1) ) { term_t a = PL_new_term_ref(); PL_get_arg(1, out, a); return PL_unify_string_nchars(a, len, (const char *)data); } PL_fail; } static foreign_t pl_bitvector_union(term_t t1, term_t t2, term_t u) { unsigned char *s1, *s2; int l1, l2; if ( get_bitvector(t1, &l1, &s1) && get_bitvector(t2, &l2, &s2) ) { int l = max(l1, l2); unsigned char *s3 = alloca(l); if ( s3 ) { int n; int ml = min(l1, l2); for(n=0; n state.h \end{code} \noindent \item Embed Prolog as in the example below. Instead of calling the toplevel you probably want to call your application code. \begin{code} #include #include "state.h" int main(int argc, char **argv) { if ( !PL_set_resource_db_mem(state, state_len) || !PL_initialise(argc, argv) ) PL_halt(1); return PL_toplevel(); } \end{code} \noindent \end{enumerate} Alternative to \program{xxd}, it is possible to use inline assembler, e.g. the \program{gcc} \const{incbin} instruction. Code for \program{gcc} was provided by Roberto Bagnara on the SWI-Prolog mailinglist. Given the state in a file \file{state}, create the following assembler program: \begin{code} .globl _state .globl _state_end _state: .incbin "state" _state_end: \end{code} \noindent Now include this as follows: \begin{code} #include #if __linux #define STATE _state #define STATE_END _state_end #else #define STATE state #define STATE_END state_end #endif extern unsigned char STATE[]; extern unsigned char STATE_END[]; int main(int argc, char **argv) { if ( !PL_set_resource_db_mem(STATE, STATE_END - STATE) || !PL_initialise(argc, argv) ) PL_halt(1); return PL_toplevel(); } \end{code} \noindent As Jose Morales pointed at \url{https://github.com/graphitemaster/incbin}, which contains a portability layer on top of the above idea. \cfunction{int}{PL_toplevel}{} Runs the goal of the \argoption{-t}{toplevel} switch (default \index{prolog/0}\predref{prolog}{0}) and returns 1 if successful, 0 otherwise. \cfunction{int}{PL_cleanup}{int status_and_flags} This function may be called instead of \cfuncref{PL_halt}{} to cleanup Prolog without exiting the process. It performs the reverse of \cfuncref{PL_initialise}{}. It runs the \cfuncref{PL_on_halt}{} and \index{at_halt/1}\predref{at_halt}{1} handlers, closes all streams (except for the \jargon{standard I/O} streams, which are flushed only), restores all signal handlers and reclaims all memory unless asked not to. \arg{status_and_flags} accepts the following flags: \begin{description} \definition{\const{PL_CLEANUP_NO_RECLAIM_MEMORY}} Do not reclaim memory. This is the default when called from \cfuncref{PL_halt}{} for the release versions because the OS will do so anyway. \definition{\const{PL_CLEANUP_NO_CANCEL}} Do not allow Prolog and foreign \jargon{halt} hooks to cancel the cleanup. \end{description} The return value of \cfuncref{PL_cleanup}{} is one of the following: \begin{description} \definition{\const{PL_CLEANUP_CANCELED}} A Prolog or foreign \jargon{halt} hook cancelled the cleanup. Note that some of the halt hooks may have been executed. \definition{\const{PL_CLEANUP_SUCCESS}} Cleanup completed successfully. Unless \const{PL_CLEANUP_NO_RECLAIM_MEMORY} was specified this implies most of the memory was reclaimed and Prolog may be reinitialized in the same process using \cfuncref{PL_initialise}{}. \definition{\const{PL_CLEANUP_FAILED}} Cleanup failed. This happens if the user requested to reclaim all memory but this failed because the system was not able to \jargon{join} all Prolog threads and could therefore not reclaim the memory. \definition{\const{PL_CLEANUP_RECURSIVE}} \cfuncref{PL_cleanup}{} was called from a hook called by the cleanup process. \end{description} \cfuncref{PL_cleanup}{} allows deleting and restarting the Prolog system in the same process. In versions older than 8.5.9 this did not work. As of version 8.5.9, it works for the basic Prolog engine. Many of the plugins that contain foreign code do not implement a suitable \jargon{uninstall} handler and will leak memory and possibly other resources. Note that shutting Prolog down and renitializing it is slow. For almost all scenarios there are faster alternatives such as reloading modified code, using \jargon{temporary modules}, using \jargon{threads}, etc. \cfunction{void}{PL_cleanup_fork}{} Stop intervaltimer that may be running on behalf of \index{profile/1}\predref{profile}{1}. The call is intended to be used in combination with fork(): \begin{code} if ( (pid=fork()) == 0 ) { PL_cleanup_fork(); } \end{code} \noindent The call behaves the same on Windows, though there is probably no meaningful application. \cfunction{int}{PL_halt}{int status} Clean up the Prolog environment using \cfuncref{PL_cleanup}{} and if successful call exit() with the status argument. Returns \const{FALSE} if exit was cancelled by \cfuncref{PL_cleanup}{}. \end{description} \subsubsection{Threading, Signals and embedded Prolog} \label{sec:sigembedded} This section applies to Unix-based environments that have signals or multithreading. The Windows version is compiled for multithreading, and Windows lacks proper signals. We can distinguish two classes of embedded executables. There are small C/C++ programs that act as an interfacing layer around Prolog. Most of these programs can be replaced using the normal Prolog executable extended with a dynamically loaded foreign extension and in most cases this is the preferred route. In other cases, Prolog is embedded in a complex application that---like Prolog---wants to control the process environment. A good example is Java. Embedding Prolog is generally the only way to get these environments together in one process image. Java VMs, however, are by nature multithreaded and appear to do signal handling (software interrupts). On Unix systems, SWI-Prolog installs handlers for the following signals: \begin{description} \item[SIGUSR2] has an empty signal handler. This signal is sent to a thread after sending a thread-signal (see \index{thread_signal/2}\predref{thread_signal}{2}). It causes blocking system calls to return with \const{EINTR}, which gives them the opportunity to react to thread-signals. In some cases the embedded system and SWI-Prolog may both use \const{SIGUSR2} without conflict. If the embedded system redefines \const{SIGUSR2} with a handler that runs quickly and no harm is done in the embedded system due to spurious wakeup when initiated from Prolog, there is no problem. If SWI-Prolog is initialised \emph{after} the embedded system it will call the handler set by the embedded system and the same conditions as above apply. SWI-Prolog's handler is a simple function only chaining a possibly previously registered handler. SWI-Prolog can handle spurious \const{SIGUSR2} signals. \item[SIGINT] is used by the top level to activate the tracer (typically bound to control-C). The first control-C posts a request for starting the tracer in a safe, synchronous fashion. If control-C is hit again before the safe route is executed, it prompts the user whether or not a forced interrupt is desired. \item[SIGTERM, SIGABRT and SIGQUIT] are caught to cleanup before killing the process again using the same signal. \item[SIGSEGV, SIGILL, SIGBUS, SIGFPE and SIGSYS] are caught by to print a backtrace before killing the process again using the same signal. \item[SIGHUP] is caught and causes the process to exit with status 2 after cleanup. \end{description} The \cmdlineoption{--no-signals} option can be used to inhibit all signal processing except for \const{SIGUSR2}. The handling of \const{SIGUSR2} is vital for dealing with blocking system call in threads. The used signal may be changed using the \cmdlineoption{--sigalert=NUM} option or disabled using \verb$--sigalert=0$. \section{Linking embedded applications using swipl-ld} \label{sec:plld} The utility program \program{swipl-ld} (Win32: swipl-ld.exe) may be used to link a combination of C files and Prolog files into a stand-alone executable. \program{swipl-ld} automates most of what is described in the previous sections. In normal usage, a copy is made of the default embedding template \file{.../swipl/include/stub.c}. The main() routine is modified to suit your application. \cfuncref{PL_initialise}{} \strong{must} be passed the program name (\arg{argv[0]}) (Win32: the executing program can be obtained using GetModuleFileName()). The other elements of the command line may be modified. Next, \program{swipl-ld} is typically invoked as: \begin{code} swipl-ld -o output stubfile.c [other-c-or-o-files] [plfiles] \end{code} \noindent \program{swipl-ld} will first split the options into various groups for both the C compiler and the Prolog compiler. Next, it will add various default options to the C compiler and call it to create an executable holding the user's C code and the Prolog kernel. Then, it will call the SWI-Prolog compiler to create a saved state from the provided Prolog files and finally, it will attach this saved state to the created emulator to create the requested executable. Below, it is described how the options are split and which additional options are passed. \begin{description} \cmdlineoptionitem{-help}{} Print brief synopsis. \cmdlineoptionitem{-pl}{prolog} Select the Prolog to use. This Prolog is used for two purposes: get the home directory as well as the compiler/linker options and create a saved state of the Prolog code. \cmdlineoptionitem{-ld}{linker} Linker used to link the raw executable. Default is to use the C compiler (Win32: \program{link.exe}). \cmdlineoptionitem{-cc}{C compiler} Compiler for \fileext{c} files found on the command line. Default is the compiler used to build SWI-Prolog accessible through the Prolog flag \prologflag{c_cc} (Win32: \program{cl.exe}). \cmdlineoptionitem{-c++}{C++-compiler} Compiler for C++ source file (extensions \fileext{cpp}, \fileext{cxx}, \fileext{cc} or \fileext{C}) found on the command line. Default is \program{c++} or \program{g++} if the C compiler is \program{gcc} (Win32: cl.exe). \cmdlineoptionitem{-nostate}{} Just relink the kernel, do not add any Prolog code to the new kernel. This is used to create a new kernel holding additional foreign predicates on machines that do not support the shared-library (DLL) interface, or if building the state cannot be handled by the default procedure used by \program{swipl-ld}. In the latter case the state is created separately and appended to the kernel using \exam{cat \bnfmeta{kernel} \bnfmeta{state} > \bnfmeta{out}} (Win32: \exam{copy /b \bnfmeta{kernel}+\bnfmeta{state} \bnfmeta{out}}). \cmdlineoptionitem{-shared}{} Link C, C++ or object files into a shared object (DLL) that can be loaded by the \index{load_foreign_library/1}\predref{load_foreign_library}{1} predicate. If used with \cmdlineoption{-c}{} it sets the proper options to compile a C or C++ file ready for linking into a shared object. \cmdlineoptionitem{-dll}{} \emph{Windows only}. Embed SWI-Prolog into a DLL rather than an executable. \cmdlineoptionitem{-c}{} Compile C or C++ source files into object files. This turns \program{swipl-ld} into a replacement for the C or C++ compiler, where proper options such as the location of the include directory are passed automatically to the compiler. \cmdlineoptionitem{-E}{} Invoke the C preprocessor. Used to make \program{swipl-ld} a replacement for the C or C++ compiler. \cmdlineoptionitem{-pl-options}{,\ldots} Additional options passed to Prolog when creating the saved state. The first character immediately following \const{pl-options} is used as separator and translated to spaces when the argument is built. Example: \exam{-pl-options,-F,xpce} passes \exam{-F xpce} as additional flags to Prolog. \cmdlineoptionitem{-ld-options}{,\ldots} Passes options to the linker, similar to \cmdlineoption{-pl-options}. \cmdlineoptionitem{-cc-options}{,\ldots} Passes options to the C/C++ compiler, similar to \cmdlineoption{-pl-options}. \cmdlineoptionitem{-v}{} Select verbose operation, showing the various programs and their options. \cmdlineoptionitem{-o}{outfile} Reserved to specify the final output file. \cmdlineoptionitem*{-l}{library} Specifies a library for the C compiler. By default, \clib{-lswipl} (Win32: libpl.lib) and the libraries needed by the Prolog kernel are given. \cmdlineoptionitem*{-L}{library-directory} Specifies a library directory for the C compiler. By default the directory containing the Prolog C library for the current architecture is passed. \cmdlineoptionitem{\cmdlineoption{-g} \bnfor{} \cmdlineoption{-I\arg{include-directory}} \bnfor{} \cmdlineoption{-D\arg{definition}}}{} These options are passed to the C compiler. By default, the include directory containing \file{SWI-Prolog.h} is passed. \program{swipl-ld} adds two additional \argoption*{-D}{def} flags: \begin{description} \cmdlineoptionitem*{-D}{\const{__SWI_PROLOG__}} Indicates the code is to be connected to SWI-Prolog. \cmdlineoptionitem*{-D}{\const{__SWI_EMBEDDED__}} Indicates the creation of an embedded program. \end{description} \cmdlineoptionitem{}{*.o \bnfor{} *.c \bnfor{} *.C \bnfor{} *.cxx \bnfor{} *.cpp} Passed as input files to the C compiler. \cmdlineoptionitem{}{*.pl \bnfor *.qlf} Passed as input files to the Prolog compiler to create the saved state. \cmdlineoptionitem{}{\Stimes} All other options. These are passed as linker options to the C compiler. \end{description} \subsection{A simple example} \label{sec:foreign-example} The following is a very simple example going through all the steps outlined above. It provides an arithmetic expression evaluator. We will call the application \program{calc} and define it in the files \file{calc.c} and \file{calc.pl}. The Prolog file is simple: \begin{code} calc(Atom) :- term_to_atom(Expr, Atom), A is Expr, write(A), nl. \end{code} \noindent The C part of the application parses the command line options, initialises the Prolog engine, locates the \verb$calc/1$ predicate and calls it. The coder is in \figref{calc}. \begin{figure} \begin{code} #include #include #include #define MAXLINE 1024 int main(int argc, char **argv) { char expression[MAXLINE]; char *e = expression; char *program = argv[0]; char *plav[2]; int n; /* combine all the arguments in a single string */ for(n=1; n #include #include foreign_t pl_lowercase(term_t u, term_t l) { char *copy; char *s, *q; int rval; if ( !PL_get_atom_chars(u, &s) ) return PL_warning("lowercase/2: instantiation fault"); copy = malloc(strlen(s)+1); if ( !copy ) return PL_resource_error("memory"); for( q=copy; *s; q++, s++) *q = (isupper(*s) ? tolower(*s) : *s); *q = '\0'; rval = PL_unify_atom_chars(l, copy); free(copy); return rval; } install_t install() { PL_register_foreign("lowercase", 2, pl_lowercase, 0); } \end{code} \noindent \caption{Lowercase source file} \label{fig:lowercase-c} \end{figure} \begin{figure}[htb] \begin{code} % gcc -I/usr/local/lib/swipl-\plversion/include -fpic -c lowercase.c % gcc -shared -o lowercase.so lowercase.o % swipl Welcome to SWI-Prolog (...) ... 1 ?- load_foreign_library(lowercase). true. 2 ?- lowercase('Hello World!', L). L = 'hello world!'. \end{code} \noindent \caption{Compiling the C source and loading the object file} \label{fig:load-foreign} \end{figure} \clearpage \section{Notes on Using Foreign Code} \label{sec:foreignnotes} \subsection{Foreign debugging functions} \label{sec:foreign-debug} 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 debugging using \exam{cmake -DCMAKE_BUILD_TYPE=Debug}, after which all functions and predicates listed below are available to use from the debugger (e.g. \program{gdb}) or can be placed at critical location in your code or the system code. \begin{description} \cfunction{void}{PL_backtrace}{int depth, int flags} Dump a Prolog backtrace to the \const{user_error} stream. \arg{Depth} is the number of frames to dump. \arg{Flags} is a bitwise or of the following constants: \begin{description} \termitem{PL_BT_SAFE}{} (0x1) Do not try to print \jargon{goals}. Instead, just print the predicate name and arity. This reduces the likelihood to crash if \cfuncref{PL_backtrace}{} is called in a damaged environment. \termitem{PL_BT_USER}{} (0x2) Only show `user' frames. Default is to also show frames of hidden built-in predicates. \end{description} \cfunction{char *}{PL_backtrace_string}{int depth, int flags} As \cfuncref{PL_backtrace}{}, but returns the stack as a string. The string uses UTF-8 encoding. The returned string must be freed using \cfuncref{PL_free}{}. This function is was added to get stack traces from running servers where I/O is redirected or discarded. For example, using \program{gdb}, a stack trace is printed in the gdb console regardless of Prolog I/O redirection using the following command: \begin{code} (gdb) printf "%s", PL_backtrace_string(25,0) \end{code} \noindent The source distribution provides the script \file{scripts/swipl-bt} that exploits \program{gdb} and \cfuncref{PL_backtrace_string}{} to print stack traces in various formats for a SWI-Prolog process, given its process id. \cfunction{int}{PL_check_data}{term_t data} Check the consistency of the term \arg{data}. Returns \const{TRUE} this is actually implemented in the current version and \const{FALSE} otherwise. The actual implementation only exists if the system is compiled with the cflag \const{-DO_DEBUG} or \const{-DO_MAINTENANCE}. This is \emph{not} the default. \cfunction{int}{PL_check_stacks}{} Check the consistency of the runtime stacks of the calling thread. Returns \const{TRUE} this is actually implemented in the current version and \const{FALSE} otherwise. The actual implementation only exists if the system is compiled with the cflag \const{-DO_DEBUG} or \const{-DO_MAINTENANCE}. This is \emph{not} the default. \end{description} The Prolog kernel sources use the macro \cfuncref{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 \index{prolog_debug/1}\predref{prolog_debug}{1} and \index{prolog_nodebug/1}\predref{prolog_nodebug}{1}. In addition, they can be activated from the commandline using commandline option \const{-d topics}, where \arg{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. \begin{code} $ swipl -d chk_secure,msg_signal \end{code} \noindent \begin{description} \predicate{prolog_debug}{1}{+Topic} \nodescription \predicate{prolog_nodebug}{1}{+Topic} Enable/disable a debug topic. \arg{Topic} is an atom that identifies the desired topic. The available topics are defined in \file{src/pl-debug.h}. Please search the sources to find out what is actually printed and when. We highlight one topic here: \begin{description} \termitem{chk_secure} Add many expensive consistency checks to the system. This should typically be used when the system crashes, notably in the garbage collector. Garbage collection crashes are in most cases caused by invalid data on the Prolog stacks. This debug topic may help locating how the invalid data was created. \end{description} These predicates require the system to be compiled for debugging using \exam{cmake -DCMAKE_BUILD_TYPE=Debug}. \cfunction{int}{PL_prolog_debug}{const char *topic} \nodescription \cfunction{int}{PL_prolog_nodebug}{const char *topic} (De)activate debug topics. The \arg{topics} argument is a comma-separated string of topics to enable or disable. Matching is case-insensitive. See also \index{prolog_debug/1}\predref{prolog_debug}{1} and \index{prolog_nodebug/1}\predref{prolog_nodebug}{1}. These functions require the system to be compiled for debugging using \exam{cmake -DCMAKE_BUILD_TYPE=Debug}. \end{description} \subsection{Memory Allocation} \label{sec:foreign-malloc} SWI-Prolog's heap memory allocation is based on the \manref{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 \cfuncref{PL_malloc}{} or \cfuncref{PL_realloc}{} do not return. Portable applications must use \cfuncref{PL_free}{} to release strings returned by \cfuncref{PL_get_chars}{} using the \const{BUF_MALLOC} argument. Portable applications may use both \cfuncref{PL_malloc}{} and friends or malloc() and friends but should not mix these two sets of functions on the same memory. \begin{description} \cfunction{void *}{PL_malloc}{size_t bytes} Allocate \arg{bytes} of memory. On failure SWI-Prolog's fatal-error handler is called and \cfuncref{PL_malloc}{} does not return. Memory allocated using these functions must use \cfuncref{PL_realloc}{} and \cfuncref{PL_free}{} rather than realloc() and free(). \cfunction{void *}{PL_realloc}{void *mem, size_t size} Change the size of the allocated chunk, possibly moving it. The \arg{mem} argument must be obtained from a previous \cfuncref{PL_malloc}{} or \cfuncref{PL_realloc}{} call. \cfunction{void}{PL_free}{void *mem} Release memory. The \arg{mem} argument must be obtained from a previous \cfuncref{PL_malloc}{} or \cfuncref{PL_realloc}{} call. \end{description} \subsection{Compatibility between Prolog versions} \label{sec:foreign-compat} 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. \index{PLVERSION}% Source code that relies on new features of the foreign interface can use the macro \const{PLVERSION} to find the version of \file{SWI-Prolog.h} and \cfuncref{PL_query}{} using the option \const{PL_QUERY_VERSION} to find the version of the attached Prolog system. Both follow the same numbering schema explained with \cfuncref{PL_query}{}. \subsection{Foreign hash tables} \label{sec:foreign-hash-tables} 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 (\ctype{atom_t}). An 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 \textbf{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. \begin{description} \cfunction{hash_table_t}{PL_new_hash_table}{int size, void (*free_symbol)(void *n, void *v)} Create a new table for \arg{size} key-value pairs. The table is resized when needed. If you know the table will hold 10,000 key-value pairs, providing a suitable initial size avoids resizing. The \arg{free_symbol} function is called whenever a key-value pair is removed from the table. This can be \const{NULL}. \cfunction{int}{PL_free_hash_table}{hash_table_t table} Destroy the hash table. First calls \cfuncref{PL_clear_hash_table}{}. \cfunction{void*}{PL_lookup_hash_table}{hash_table_t table, void *key} Return the value matching \arg{key} or \const{NULL} if \arg{key} does not appear in the table. \cfunction{void*}{PL_add_hash_table}{hash_table_t table, void *key, void *value, int flags} Add \arg{key}-\arg{value} to the table. The behaviour if \arg{key} is already in the table depends on \arg{flags}. If \const{0}, this function returns the existing value without updating the table. If \const{PL_HT_UPDATE} the old \arg{value} is \emph{replaced} and the function returns the old value. If \const{PL_HT_NEW}, a message and backtrace are printed and the function returns \arg{NULL} if \arg{key} is already in the table. \cfunction{void*}{PL_del_hash_table}{hash_table_t table, void *key} Delete \arg{key} from the table, returning the old associated value or \const{NULL} \cfunction{int}{PL_clear_hash_table}{hash_table_t table} Delete all key-value pairs from the table. Call \arg{free_symbol} for each deleted pair. \cfunction{hash_table_enum_t}{PL_new_hash_table_enum}{hash_table_t table} Return a table \jargon{enumerator} (cursor) that can be used to enumerate all key-value pairs using \cfuncref{PL_advance_hash_table_enum}{}. The enumerator must be discarded using \cfuncref{PL_free_hash_table_enum}{}. It is safe for another thread to add symbols while the table is being enumerated, but undefined whether or not these new symbols are visible. If another thread deletes a key that is not yet enumerated it will not be enumerated. \cfunction{void}{PL_free_hash_table_enum}{hash_table_enum_t e} Discard an enumerator object created using \cfuncref{PL_new_hash_table_enum}{}. Failure to do so causes the table to use more and more memory on subsequent modifications. \cfunction{int}{PL_advance_hash_table_enum}{hash_table_enum_t e, void **key, void **value} Get the next key-value pair from a cursor. \end{description} \subsection{Debugging and profiling foreign code (valgrind, asan)} \label{sec:foreign-debug-and-profile} \index{valgrind}\index{profiling,foreign code}% This section is only relevant for Unix users on platforms supported by \href{http://valgrind.org/}{valgrind}. Valgrind is an excellent binary instrumentation platform. Unlike many other instrumentation platforms, valgrind can deal with code loaded through dlopen(). The \program{callgrind} tool can be used to profile foreign code loaded under SWI-Prolog. Compile the foreign library adding \cmdlineoption{-g} option to \program{gcc} or \program{swipl-ld}. By setting the environment variable \env{VALGRIND} to \const{yes}, SWI-Prolog will \emph{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.\footnote{Tested using valgrind version 3.2.3 on x64.} Here is the complete sequence using \program{bash} as login shell: \begin{code} % VALGRIND=yes valgrind --tool=callgrind pl % kcachegrind callgrind.out. \end{code} \noindent \index{asan}\index{profiling,foreign code}% Instead of \program{valgrind}, you can use \href{https://github.com/google/sanitizers/wiki/AddressSanitizer}{AddressSanitizer}. Here is a short example for building with \jargon{asan} enabled and then running the resulting binary. When you exit \program{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. \begin{code} % cd build.sanitize % cmake -G Ninja -DCMAKE_BUILD_TYPE=Sanitize .. % ninja % ASAN_OPTIONS=detect_leaks=1 build.sanitize/src/swipl % halt Running LSAN memory leak check (reclaim_memory=1) No leaks detected \end{code} \noindent \subsection{Name Conflicts in C modules} \label{sec:foreign-name-conflicts} 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: \begin{code} #define warning warning_ \end{code} \noindent 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. \subsection{Compatibility of the Foreign Interface} \label{sec:foreign-quintus-sicstus} 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 \const{+term}. SWI-Prolog explicitly uses type \ctype{functor_t}, while Quintus and SICStus use \bnfmeta{name} and \bnfmeta{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 example: \begin{code} #define QP_put_functor(t, n, a) \ PL_put_functor(t, PL_new_functor(n, a)) \end{code} \noindent The {\tt 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 \cfuncref{PL_open_foreign_frame}{}/\cfuncref{PL_close_foreign_frame}{} combination is lacking from both other Prologs. SICStus has \cfuncref{PL_new_term_refs}{0}, followed by \cfuncref{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. % SWI-Stream.h docs \input{streams.tex}