========================================================
(C)1993, 1994 Institute for New Generation Computer Technology
(Read COPYRIGHT for detailed information.)
========================================================

Inline C Code
=============
December 2, 1993
Last revision: February 1, 1994
Takashi Chikayama (ICOT)

The inline C code feature allows specifying C programs to be inserted
in the object code from within KL1 programs.  This feature is somewhat
similar to "asm" statements of C.

Note: The correctness of the inserted C code depends heavily on
internal implementation schemes of the KLIC system, which may be
altered in future.  Thus, general users are not recommended to use
this feature.


1. Inline Insersion Specification at the Top of Source Files

At the top of a source file, strings to be inserted in the object C
program can be specified in the following way.

	:- inline:"C Program Text to be Inserted".

The specified text is inserted in the object C program after standard
declarations and before any user-defined modules.

There can be any number of such inline specification.  A typical
example is as follows.

	:- inline:"#include <stdio.h>"

In the insersion string, doubleqoute characters have to be written
twice to mean one doublequote.  Percent characters also have to be
written twice.  A typical example is as follows.

	:- inline:"#include ""myheader.h"""

It might also be a good idea to define macros and functions here, that
are invoked from within the inline code in clause guards (see below).


2. Inline Insersion Specification in the Guard

Inline insertion specification can also appear as a guard goal with
one of the following forms.

	inline:"C Program Text"
	inline:"C Program Text":[ArgSpec, ...]

With either format, the C program text is literally inserted in the
object code corresponding to the guard part, except that percent signs
('%') in the program text string specify special formatting.  The
following lists the special format characters following the percent
sign and their meaning.

	Format Char		Meaning

	 <digit>	The name of the C variable corresponding to
			the digit'th ArgSpec (zero origin).  Note that
			only up to 10 such argument is allowed.

	    f		The name of the C label to "goto" when this
			clause should fail or suspend.

	    %		The percent character itself, i.e., percent
			characters should be doubled.

The ArgSpec has one of the following format.

 Variable+Type		(input mode)
	Specifies that the value of the variable is used within the
	inserted program text.  Object code is generated for proper
	synchronization and type checking by the compiler.

 Variable-Type		(output mode)
	Specifies that variable is given a value within the inserted
	program text.  This has to be the first occurence of the
	variable.  The compiler assumes that, after executing the
	inserted code, the variable will have value of Type.

The Type field should be one of the following.

	Type			Meaning

	any		Anything, including uninstantiated variables

	bound		Any bound value

	atomic		An atomic value (an atom or an integer)

	int		An integer

	atom		An symbolic atom

	list		A list structure

	functor		A functor structure (including generic object)

	object		A data generic object

	object(Class)	A data generic object of the class

No indirections are allowed for all types except for "any".  For an
input ('+') mode argument, the compiler will make sure that, before
executing the inserted program text, the argument will have the value
of the specified type directly without indirect references.  For an
output ('-') mode argument, the compiler assumes that, after executing
the inserted program text, the variable will have the value of the
specified type directly without any indirect references, and uses that
information for optimization.


3. C Level Representation of KL1 Values

Note that types of the C variables corresponding to a KL1 variable is
not the same as the value of the KL1 variable.  All the C variables
corresponding to KL1 variables have the type "q" which means almost
nothing except that it occupies one word.  Also, KL1 values are
somehow encoded (with attached tag &c).  For example, an integer 3 of
KL1 is _not_ represented by the bit pattern corresponding to integer 3
in the C level.

This document is not intended to describe all the detailes of the data
representation.  However, the most frequently useful may be conversion
between integers of C and KL1.  To obtain the integer value of a
variable corresponding to an integer value of KL1, use the macro
intval(x).  To obtain KL1 representation of integer in C, use the
macro makeint(n).


4. Exmaples

[Example 1] Adding two integers

Two integers can be added by the following clause.

    p(X,Y,Z) :- W := X+Y | Z = W.

The same function can be realized using the inline insertion feature
as follows.

    p(X,Y,Z) :-
      inline:"%2 = makeint(intval(%0)+intval(%1));":
        [X+int, Y+int, W-int] | Z=W.

The inserted text will be as follows.

    x0 = makeint(intval(a0)+intval(a1));

Where variables a0 and a1 correspond to X and Y, and x0 to W in the
KL1 program.

[Example 2] Comparing two integers

Two integers can be compared by the following clause.

   p(X,Y) :- X > Y | ...

The same function can be realized using the inline insertion feature
as follows.

    p(X,Y) :-
      inline:"if (intval(%0) <= intval(%1)) goto %f;":
        [X+int, Y+int] | ...

The inserted text will be as follows.

    if (intval(a0) <= intval(a1)) goto p_2_interrupt;

Where variables a0 and a1 correspond to X and Y in the KL1 program,
and p_2_interrupt is a label automatically generated by the compiler.


5. Pitfalls

- Avoid using the inline feature as far as possible.  Revisions of the
  KLIC system may obsolete your code.

- If multiple lines are to be inserted consecutively, specify all of
  them in one single inline specification.  Otherwise, they might be
  interleaved by other code for the guard.  Newlines are allowed
  within the program text string to be inserted.

If you think something's wrong, the best way to find the problem is to
look into the C code generated.


6. Bugs

- Error diagnosis for inline expansion by the compiler is quite
  unfriendly.

- Cleaner and higher-level interface is desired.
