@c -*-texinfo-*-
@node Low Level Foreign, PredicateIndex, Low Level, Top
@comment  node-name,  next,  previous,  up
@appendix Low Level Foreign Language Interface 

ICP offers two interfaces to functions written in the programming language 
C.  The first scheme is compatible with most other Prologs and has
been described previously in this manual.  However it suffers from the
restriction that only numbers and strings may be passed between the
two languages.

The second scheme described here is more powerful since it allows C
to examine, manipulate and construct Prolog structures and lists.
The Prolog side of the interface is very simple: the user needs 
to provide the mapping of Prolog predicate name and arity to the 
corresponding C function. On the C side, things are more complicated
and the programmer needs to understand about the internal structure
of Prolog data before being able to write primitives effectively.
A suite of functions to analyse, unify and instantiate Prolog
arguments is provided to support this.

C functions are all of type @code{bool} (defined in file @file{icp.h})
and have 0 arguments. The real arguments are accessed through the C
global variable A, which is an array of @var{cells}.  A @var{cell}
holds either a number, a string or a pointer called a cellpo.
A cellpo simply points to another cell.

The first argument
is in A[1], the second argument in A[2] etc.  Before accessing
an argument, any variable to variable link must be followed.

@menu
* Interface Predicates::        Prolog Interface Predicates
* C interface::                 C interface functions 
@end menu

@node Interface Predicates, C interface,  , Low Level Foreign
@comment  node-name,  next,  previous,  up
@appendixsec Prolog Interface Predicates 

@table @code
@item load_foreign(@var{+File}, @var{+List})
@findex load_foreign/2
The object level file @var{File}@file{.o} defines the predicates in 
@var{List}. @var{List} is a list of terms which can have one of the 
following forms.

@table @code
@item Name/Arity
The predicate, @var{Name}, of arity @var{Arity} is defined 
by the C function @var{Name}. Thus for example the term @code{someCfunc/2} 
refers to a C function of the form
@example
bool someCfunc()
@{
    @dots{}
@}
@end example
@item Name/Arity=Cname
The predicate, @var{Name}, of arity @var{Arity} is 
defined by the C function @var{Cname}. Thus for example the term 
@code{someCfunc/2=fancyname} refers to a C function of the form
@example
bool fancyname()
@{
    @dots{}
@}
@end example
@end table

@item load_foreign(@var{+File}, @var{+List}, @var{+Lib})
@findex load_foreign/3
As @code{load_foreign/2} but also use libraries @var{Lib}.  @var{Lib}
is either an atom or a list of atoms representing the filenames of
the library files.
@end table

@node C interface,  , Interface Predicates, Low Level Foreign
@comment  node-name,  next,  previous,  up
@appendixsec C interface functions 
As mentioned previously, C functions to be called by Prolog have no 
arguments and are of type boolean. The functions should return one of the 
following integers (defined in icp.h).

@table @code
@item FAIL
The Prolog will fail.
@item SUCCEED
The Prolog will succeed.
@item SUSPEND
If a primitive returns SUSPEND, then that thread is taken out of
the run queue.  This means that another thread will have to explicitly
`resume' it before it can run again.
@item REQUEUE
REQUEUE means the primitive should be tried again later. This
can result in a busy wait if nothing happens in between to change the status.
@end table

@menu
* Analyzing Prolog Terms::      Analyzing Prolog Terms 
* Constructing Terms::          Constructing and Instantiating Terms 
@end menu

@node Analyzing Prolog Terms, Constructing Terms,  , C interface
@comment  node-name,  next,  previous,  up
@appendixsubsec Analyzing Prolog Terms 

Prolog terms are all of type @kbd{cellpo}. Each term is a tagged cell,
consisting of a tag and a value field.  The tag determines the type of
the cell.  The types of Prolog terms are

@table @code
@item symbol
ICP symbols are pointers to C structures containing a 2 byte length field,
a 2 byte hash code field and the print name of the symbol as a C string.
@item integer
ICP integers are stored as tagged C longs. The range of integers is
FC000000 --- 03FFFFFF (-67108864 to 67108863 in decimal).
@item float
ICP floats are pointers to C double precision numbers.  This has a 52 bit
mantissa and a 11 bit exponent.
@item variable
ICP variables are pointers pointing to itself.
@item nil
Nil represents the empty list.
@item list
ICP lists are pointers to pairs of cells in the manner of linked lists.
The first of the pair is the head of the list, and the second cell is the tail.
@item structures
ICP structures are represented as tuples.  This is a pointer to a block
of cells the first of which specifies the length of the tuple.  The second
cell is what is normally termed the functor and is usually an ICP symbol.
The rest of the cells represent the arguments of the structure.
@end table

Testing of Prolog arguments are performed by the following functions of
type int.

@table @kbd
@item IsVar(addr)
@*addr is an unbound Prolog variable.
@item IsInt(addr)
@*addr is a Prolog integer.
@item IsFloat(addr)
@*addr is a Prolog floating point number.
@item IsSymb(addr)
@*addr is a Prolog atom.
@item IsNil(addr)
@*addr is a Prolog empty list.
@item IsList(addr)
@*addr is a Prolog list with at least one element.
@item IsTpl(addr)
@*addr is a Prolog tuple.
@item NotVar(addr)
equivalent to @kbd{(! IsVar(addr))}.
@item NotInt(addr)
equivalent to @kbd{(! IsInt(addr))}.
@item NotFloat(addr)
equivalent to @kbd{(! IsFloat(addr))}.
@item NotSymb(addr)
equivalent to @kbd{(! IsVar(addr))}.
@item NotNil(addr)
equivalent to @kbd{(! IsNil(addr))}.
@item NotList(addr)
equivalent to @kbd{(! IsList(addr))}.
@item NotTpl(addr)
equivalent to @kbd{(! IsTpl(addr))}.
@end table

Converting arguments from Prolog to C is achieved by the following C 
functions:

@table @kbd
@item long intvl(x)
Converts from the Prolog representation of an 
integer to a C long.
@item double floatvl(x)
Converts from the Prolog representation of a 
float to a C double.
@item char *string_val(arg)
Converts from the Prolog representation of an atom to a C string.
@item cellpo hd(arg)
@item cellpo tl(arg)
@item cellpo arity(arg)
@item cellpo functor(arg)
@item cellpo arg(cell,n)
@end table

@node Constructing Terms,  , Analyzing Prolog Terms, C interface
@comment  node-name,  next,  previous,  up
@appendixsubsec Constructing and Instantiating Terms 

To be written.
