Foreign Language Interface Properties

Author(s): Jose Morales, Manuel Carro.

Version: 1.11#222 (2004/5/24, 13:8:7 CEST)

Version of last change: 1.11#216 (2004/3/26, 20:8:6 CET)

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 (foreign_interface_properties)
• Documentation on exports (foreign_interface_properties)
• Documentation on internals (foreign_interface_properties)
• Known bugs and planned improvements (foreign_interface_properties)

Usage and interface (foreign_interface_properties)

Documentation on exports (foreign_interface_properties)

REGTYPE: int_list/1:

Usage: int_list(List)

• Description: List is a list of integers.

REGTYPE: byte_list/1:

Usage: byte_list(List)

• Description: List is a list of bytes.

REGTYPE: byte/1:

Usage: byte(Byte)

• Description: Byte is a byte.

REGTYPE: null/1:

Usage: null(Address)

• Description: Address is a null adress.

REGTYPE: address/1:

Usage: address(Address)

• Description: Address is a memory address.

REGTYPE: any_term/1:

Usage: any_term(X)

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

PROPERTY: native/1:

Usage: native(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: native/2:

Usage: native(PrologName, ForeignName)

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

PROPERTY: size_of/3:

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: foreign/1:

Usage: foreign(Name)

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

PROPERTY: foreign/2:

Usage: foreign(PrologName, ForeignName)

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

PROPERTY: returns/2:

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: do_not_free/2:

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.

Documentation on internals (foreign_interface_properties)

DECLARATION: use_foreign_source/1:

Usage: :- use_foreign_source(Files).

• Description: Files is the (list of) foreign file(s) that will be linked with the glue-code file.
• The following properties hold at call time: Files is an atom or a list of atoms. (basic_props:atm_or_atm_list/1)

DECLARATION: use_foreign_source/2:

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: OsArch is an atom. (basic_props:atm/1) Files is an atom or a list of atoms. (basic_props:atm_or_atm_list/1)

DECLARATION: use_foreign_library/1:

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: Libs is an atom or a list of atoms. (basic_props:atm_or_atm_list/1)

DECLARATION: use_foreign_library/2:

Usage: :- use_foreign_library(OsArch, Libs).

• Description: Libs are the OS and architecture dependant libraries.
• The following properties hold at call time: OsArch is an atom. (basic_props:atm/1) Libs is an atom or a list of atoms. (basic_props:atm_or_atm_list/1)

DECLARATION: extra_compiler_opts/1:

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: Opts is an atom or a list of atoms. (basic_props:atm_or_atm_list/1)

DECLARATION: extra_compiler_opts/2:

Usage: :- extra_compiler_opts(OsArch, Opts).

• Description: Opts are the OS and architecture dependant additional compiler options.
• The following properties hold at call time: OsArch is an atom. (basic_props:atm/1) Opts is an atom or a list of atoms. (basic_props:atm_or_atm_list/1)

DECLARATION: use_compiler/1:

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: Compiler is an atom. (basic_props:atm/1)

DECLARATION: use_compiler/2:

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: OsArch is an atom. (basic_props:atm/1) Compiler is an atom. (basic_props:atm/1)

DECLARATION: extra_linker_opts/1:

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: Opts is an atom or a list of atoms. (basic_props:atm_or_atm_list/1)

DECLARATION: extra_linker_opts/2:

Usage: :- extra_linker_opts(OsArch, Opts).

• Description: Opts are the OS and architecture dependant additional linker options.
• The following properties hold at call time: OsArch is an atom. (basic_props:atm/1) Opts is an atom or a list of atoms. (basic_props:atm_or_atm_list/1)

DECLARATION: use_linker/1:

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: Linker is an atom. (basic_props:atm/1)

DECLARATION: use_linker/2:

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: OsArch is an atom. (basic_props:atm/1) Linker is an atom. (basic_props:atm/1)

DECLARATION: foreign_inline/2:

Usage 1: :- 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: Term is a Name/Arity structure denoting a predicate name:

  predname(P/A) :-
          atm(P),
          nnegint(A).
  

  (basic_props:predname/1) Text is a string (a list of character codes). (basic_props:string/1)

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

• Description: This usage of foreign_inline is to add globally the C source code that are in Text.
• The following properties hold at call time: Term is a free variable. (term_typing:var/1) Text is a string (a list of character codes). (basic_props:string/1)

Known bugs and planned improvements (foreign_interface_properties)

• The size_of/3 property has an empty definition

Go to the first, previous, next, last section, table of contents.