Chapter 11
Foreign Language Interface

11.1	Foreign Export

11.2	Using ABC instructions

The tool htoclean can be used to generate interfaces to C functions. This is not discussed in this manual.

How to call Clean functions from C is discussed in section 11.1.

ABC instructions of the virtual machine for Clean can be used. This is explained in section 11.2.

11.1  Foreign Export

Some Clean functions can be called from C using foreign export. This is possible if:

•         The function is exported.

•         All arguments are annotated as being strict (see 3.7.5).

•         The arguments and result type is either of the following:

•        Int

•        Real

•        {#Char}

•        {#Int}

•        {#Real}

•        A tuple of these strictly annotated types (including tuples),       

The following syntax is used in an implementation module to export a function to a foreign language:

ForeignExportDef

=

foreign export [ ccall | stdcall ] FunctionName ;

The calling convention may be specified by prefixing the function name with ccall  or stdcall. The default is ccall,

To pass an argument from C of type:

•          Int, use a C integer type that has the same size as an Int in Clean. On 32 bit platforms this is 4 bytes, on 64 bit platforms 8 bytes. Usually long has the right size, except on 64 bit Windows __int64 can be used instead.

•         Real, use type double.

•         {#Char}, pass the address of the string. The first 4 (on 32 bit platforms) or 8 (on 64 bit platforms) bytes should contain the number of characters. The characters of the string are stored in the following bytes. The string is copied to the heap of Clean, and this copy is used in Clean.

•         {#Int}, pass the address of the array. The elements of the array have the same size as an Int in Clean. The number of elements should be stored in 4 bytes at offset -8 (32 bit) or 8 bytes at offset –16 (64 bit). The array is copied to the heap of Clean, and this copy is used in Clean.

•         {#Real}, pass the address of the array. The elements of the array have the same size as a Real in Clean (8 bytes) and a double in C. The number of elements should be stored in the same way as for {#Int}. The array is copied to the heap of Clean, and this copy is used in Clean.

•         tuple. The elements are passed as separate arguments as described above, in the same order as in the tuple.

Preferably, the macros in the file Clean.h (part of the tool htoclean) should be used to access strings and arrays,

If result of the function is not a tuple, the result is passed in the same way as an argument, except that strings and arrays are not copied. The address of the string or array in the heap of Clean is passed to C. This string or array may only be used until the next call or return to Clean, because the Clean runtime system may deallocate or move the array.

If multiple values are yielded, because the result is a tuple, the result type in C is void. To return the values, for each value an additional argument with the address where the result should be stored is added (at the end, in the same order as in the tuple).  For example, if the result has type (Real, Int), an additional double * and long * (__int64 * for 64 bit Windows) is added.

11.2  Using ABC instructions

Function can be implemented using ABC instructions from the virtual machine used by Clean:

ABCCodeFunctionDef

=

Function {Pattern} = code [inline] { ABCInstructions }

By adding inline the ABC instructions will be inlined if the function is called in a strict context.

This is used to define primitive functions of the StdEnv, for example integer addition. htoclean generates calls to C functions using the ABC instruction ccall.