▲◄►The Ciao System » PART VIII - Interfaces to other languages and systems »

Foreign Language Interface Properties

Author(s): Jose F. Morales, Manuel Carro.

The foreign language interface uses some properties to specify linking regimes, foreign files to be compiled, types of data available, memory allocation policies, etc.

Usage and interface

Library usage:
:- use_module(library(foreign_interface/foreign_interface_properties)).
Exports:
- Properties:
  size_of/3, do_not_free/2, ttr/3, returns/2, needs_ciao_ctx/1, foreign/1, foreign/2, foreign_low/1, foreign_low/2.
- Regular Types:
  any_term/1, address/1, null/1, c_short/1, c_int/1, c_long/1, c_ushort/1, c_uint/1, c_ulong/1, c_uintptr/1, c_size/1, c_float/1, c_double/1, c_int8/1, c_int8/1, c_int8/1, c_int16/1, c_int32/1, c_int64/1, c_uint8/1, c_uint16/1, c_uint32/1, c_uint64/1, c_uint8_list/1, c_int_list/1, c_double_list/1.
Imports:
- Packages:
  prelude, nonpure, condcomp, assertions, regtypes.

Documentation on exports

REGTYPE

Usage:any_term(X)

X is any term. The foreign interface passes it to C functions as a general term.

REGTYPE

Usage:address(Address)

Address is a memory address.

REGTYPE

Usage:null(Address)

Address is a null adress.

REGTYPE

Usage:c_short(X)

X is an integer in the range of C short.

REGTYPE

Usage:c_int(X)

X is an integer in the range of C int.

REGTYPE

Usage:c_long(X)

X is an integer in the range of C long.

REGTYPE

Usage:c_ushort(X)

X is an integer in the range of C unsigned short.

REGTYPE

Usage:c_uint(X)

X is an integer in the range of C unsigned int.

REGTYPE

Usage:c_ulong(X)

X is an integer in the range of C unsigned long.

REGTYPE

Usage:c_uintptr(X)

X is an integer in the range of C uintptr_t.

REGTYPE

Usage:c_size(X)

X is an integer in the range of C size_t.

REGTYPE

Usage:c_float(X)

X is an integer in the range of C float.

REGTYPE

Usage:c_double(X)

X is an integer in the range of C double.

REGTYPE

Usage 1:c_int8(X)

X is an integer in the range of C int8_t.

Usage 2:c_int8(X)

X is an integer in the range of C int8_t.

Usage 3:c_int8(X)

X is an integer in the range of C int8_t.

REGTYPE

Usage 1:c_int8(X)

X is an integer in the range of C int8_t.

Usage 2:c_int8(X)

X is an integer in the range of C int8_t.

Usage 3:c_int8(X)

X is an integer in the range of C int8_t.

REGTYPE

Usage 1:c_int8(X)

X is an integer in the range of C int8_t.

Usage 2:c_int8(X)

X is an integer in the range of C int8_t.

Usage 3:c_int8(X)

X is an integer in the range of C int8_t.

REGTYPE

Usage:c_int16(X)

X is an integer in the range of C int16_t.

REGTYPE

Usage:c_int32(X)

X is an integer in the range of C int32_t.

REGTYPE

Usage:c_int64(X)

X is an integer in the range of C int64_t.

REGTYPE

Usage:c_uint8(X)

X is an integer in the range of C uint8_t.

REGTYPE

Usage:c_uint16(X)

X is an integer in the range of C uint16_t.

REGTYPE

Usage:c_uint32(X)

X is an integer in the range of C uint32_t.

REGTYPE

Usage:c_uint64(X)

X is an integer in the range of C uint64_t.

REGTYPE

c_uint8_list/1:

Usage:c_uint8_list(List)

List is a list of c_uint8/1.

REGTYPE

Usage:c_int_list(List)

List is a list of c_int/1.

REGTYPE

c_double_list/1:

Usage:c_double_list(List)

List is a list of c_double/1.

PROPERTY

Usage:size_of(Name,ListVar,SizeVar)

For predicate Name, the size of the argument of type c_uint8_list/1, ListVar, is given by the argument of type integer SizeVar.

PROPERTY

Usage:do_not_free(Name,Var)

For predicate Name, the C argument passed to (returned from) the foreign function will not be freed after calling the foreign function.

PROPERTY

Usage:ttr(Name,Var,TTr)

For predicate Name, the C argument will be translated using TTr as term translator.

PROPERTY

Usage:returns(Name,Var)

The result of the foreign function that implements the Prolog predicate Name is unified with the Prolog variable Var. Cannot be used without foreign/1 or foreign/2.

PROPERTY

needs_ciao_ctx/1:

Usage:needs_ciao_ctx(Name)

The foreign function which implementes the predicate Name needs a ciao_ctx as its first argument.

PROPERTY

Usage:foreign(Name)

The Prolog predicate Name is implemented using the foreign function Name.

PROPERTY

Usage:foreign(PrologName,ForeignName)

The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PROPERTY

Usage:foreign_low(Name)

The Prolog predicate Name is implemented using the function Name. The implementation is not a common C one, but it accesses directly the internal Ciao Prolog data structures and functions, and therefore no glue code is generated for it.

PROPERTY

Usage:foreign_low(PrologName,ForeignName)

The Prolog predicate PrologName is implemented using the function ForeignName. The same considerations as above example are to be applied.

Documentation on internals

DECLARATION

use_foreign_source/1:

(True) Usage::- use_foreign_source(Files).

Files is the (list of) foreign file(s) that will be linked with the glue-code file. If the file(s) do(es) not have extension, then the '.c' extension will be automatically added

The following properties hold at call time:
(basic_props:atm_or_atm_list/1)Files is an atom or a list of atoms.

DECLARATION

use_foreign_source/2:

(True) Usage::- use_foreign_source(OsArch,Files).

Files are the OS and architecture dependant foreign files. This allows compiling and linking different files depending on the O.S. and architecture.

The following properties hold at call time:
(basic_props:atm/1)OsArch is an atom.
(basic_props:atm_or_atm_list/1)Files is an atom or a list of atoms.

DECLARATION

use_foreign_library/1:

(True) Usage::- use_foreign_library(Libs).

Libs is the (list of) external library(es) needed to link the C files. Only the short name of the library (i.e., what would follow the -l in the linker is needed.

The following properties hold at call time:
(basic_props:atm_or_atm_list/1)Libs is an atom or a list of atoms.

DECLARATION

use_foreign_library/2:

(True) Usage::- use_foreign_library(OsArch,Libs).

Libs are the OS and architecture dependant libraries.

The following properties hold at call time:
(basic_props:atm/1)OsArch is an atom.
(basic_props:atm_or_atm_list/1)Libs is an atom or a list of atoms.

DECLARATION

extra_compiler_opts/1:

(True) Usage::- extra_compiler_opts(Opts).

Opts is the list of additional compiler options (e.g., optimization options) that will be used during the compilation.

The following properties hold at call time:
(basic_props:atm_or_atm_list/1)Opts is an atom or a list of atoms.

DECLARATION

extra_compiler_opts/2:

(True) Usage::- extra_compiler_opts(OsArch,Opts).

Opts are the OS and architecture dependant additional compiler options.

The following properties hold at call time:
(basic_props:atm/1)OsArch is an atom.
(basic_props:atm_or_atm_list/1)Opts is an atom or a list of atoms.

DECLARATION

use_compiler/1:

(True) Usage::- use_compiler(Compiler).

Compiler is the compiler to use in this file. When this option is used, the default (Ciao-provided) compiler options are not used; those specified in extra_compiler_options are used instead.

The following properties hold at call time:
(basic_props:atm/1)Compiler is an atom.

DECLARATION

use_compiler/2:

(True) Usage::- use_compiler(OsArch,Compiler).

Compiler is the compiler to use in this file when compiling for the architecture OsArch. The option management is the same as in use_compiler/2.

The following properties hold at call time:
(basic_props:atm/1)OsArch is an atom.
(basic_props:atm/1)Compiler is an atom.

DECLARATION

extra_linker_opts/1:

(True) Usage::- extra_linker_opts(Opts).

Opts is the list of additional linker options that will be used during the linkage.

The following properties hold at call time:
(basic_props:atm_or_atm_list/1)Opts is an atom or a list of atoms.

DECLARATION

extra_linker_opts/2:

(True) Usage::- extra_linker_opts(OsArch,Opts).

Opts are the OS and architecture dependant additional linker options.

The following properties hold at call time:
(basic_props:atm/1)OsArch is an atom.
(basic_props:atm_or_atm_list/1)Opts is an atom or a list of atoms.

DECLARATION

(True) Usage::- use_linker(Linker).

Linker is the linker to use in this file. When this option is used, the default (Ciao-provided) linker options are not used; those specified in extra_linker_options/1 are used instead.

The following properties hold at call time:
(basic_props:atm/1)Linker is an atom.

DECLARATION

(True) Usage::- use_linker(OsArch,Linker).

Compiler is the linker to use in this file when compiling for the architecture OsArch. The option management is the same as in use_compiler/2.

The following properties hold at call time:
(basic_props:atm/1)OsArch is an atom.
(basic_props:atm/1)Linker is an atom.

DECLARATION

foreign_inline/2:

(True) Usage::- foreign_inline(Term,Text).

Term is a predicate name. Text is a source C code that define the predicate Term. Term is present for future use with the analyzers. Example of this can be viewed in the hrtimer library.

The following properties hold at call time:
(basic_props:predname/1)
Term is a Name/Arity structure denoting a predicate name:
```
predname(P/A) :-
        atm(P),
        nnegint(A).
```
(basic_props:string/1)Text is a string (a list of character codes).

Known bugs and planned improvements

The size_of/3 property has an empty definition
The range of integer types is missing.
ciao_fits_in_X() is implemented only for a few ctypes.
X_list/1 type is implemented only for a few ctypes.
Creation if c_int64 in 32-bit build is broken (we need a MakeInteger32 and MakeInteger64)
The size_of/3 property has an empty definition