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

Documentation on exports

REGTYPE

Usage: int_list(List)

  • Description: List is a list of integers.

REGTYPE

Usage: double_list(List)

  • Description: List is a list of numbers.

REGTYPE

Usage: byte_list(List)

  • Description: List is a list of bytes.

REGTYPE

Usage: byte(B)

  • Description: Byte is a byte.

REGTYPE

Usage: null(Address)

  • Description: Address is a null adress.

REGTYPE

Usage: address(Address)

  • Description: Address is a memory address.

REGTYPE

Usage: any_term(X)

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

PROPERTY

Usage: foreign_low(Name)

  • Description: 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)

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

PROPERTY

Usage: size_of(Name,ListVar,SizeVar)

  • Description: For predicate Name, the size of the argument of type byte_list/1, ListVar, is given by the argument of type integer SizeVar.

PROPERTY

Usage: foreign(Name)

  • Description: The Prolog predicate Name is implemented using the foreign function Name.

PROPERTY

Usage: foreign(PrologName,ForeignName)

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

PROPERTY

Usage: returns(Name,Var)

  • Description: 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

Usage: do_not_free(Name,Var)

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

PROPERTY

Usage: needs_state(Name)

  • Description: The foreign function which implementes the predicate Name needs a ciao_state as its first argument.

PROPERTY

Usage: ttr(Name,Var,TTr)

  • Description: For predicate Name, the C argument will be translated ussing TTr as term translator.

Documentation on internals

DECLARATION

Usage: :- use_foreign_source(Files).

  • Description: 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

Usage: :- use_foreign_source(OsArch,Files).

  • Description: 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

Usage: :- use_foreign_library(Libs).

  • Description: 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

Usage: :- use_foreign_library(OsArch,Libs).

  • Description: 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

Usage: :- extra_compiler_opts(Opts).

  • Description: 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

Usage: :- extra_compiler_opts(OsArch,Opts).

  • Description: 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

Usage: :- use_compiler(Compiler).

  • Description: 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

Usage: :- use_compiler(OsArch,Compiler).

  • Description: 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

Usage: :- extra_linker_opts(Opts).

  • Description: 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

Usage: :- extra_linker_opts(OsArch,Opts).

  • Description: 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

Usage: :- use_linker(Linker).

  • Description: 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

Usage: :- use_linker(OsArch,Linker).

  • Description: 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

Usage: :- foreign_inline(Term,Text).

  • Description: 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 byte/1 property has an empty definition. A possible right definition is commented.