Foreign language interface properties

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

The C 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.

Documentation on exports

REGTYPEany_term/1

Usage:any_term(X)

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

REGTYPEaddress/1

Usage:address(Address)

Address is a memory address.

REGTYPEnull/1

Usage:null(Address)

Address is a null address.

REGTYPEc_short/1

Usage:c_short(X)

X is an integer in the range of C short.

REGTYPEc_int/1

Usage:c_int(X)

X is an integer in the range of C int.

REGTYPEc_long/1

Usage:c_long(X)

X is an integer in the range of C long.

REGTYPEc_ushort/1

Usage:c_ushort(X)

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

REGTYPEc_uint/1

Usage:c_uint(X)

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

REGTYPEc_ulong/1

Usage:c_ulong(X)

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

REGTYPEc_uintptr/1

Usage:c_uintptr(X)

X is an integer in the range of C uintptr_t.

REGTYPEc_size/1

Usage:c_size(X)

X is an integer in the range of C size_t.

REGTYPEc_float/1

Usage:c_float(X)

X is an integer in the range of C float.

REGTYPEc_double/1

Usage:c_double(X)

X is an integer in the range of C double.

REGTYPEc_int8/1

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.

REGTYPEc_int8/1

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.

REGTYPEc_int8/1

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.

REGTYPEc_int16/1

Usage:c_int16(X)

X is an integer in the range of C int16_t.

REGTYPEc_int32/1

Usage:c_int32(X)

X is an integer in the range of C int32_t.

REGTYPEc_int64/1

Usage:c_int64(X)

X is an integer in the range of C int64_t.

REGTYPEc_uint8/1

Usage:c_uint8(X)

X is an integer in the range of C uint8_t.

REGTYPEc_uint16/1

Usage:c_uint16(X)

X is an integer in the range of C uint16_t.

REGTYPEc_uint32/1

Usage:c_uint32(X)

X is an integer in the range of C uint32_t.

REGTYPEc_uint64/1

Usage:c_uint64(X)

X is an integer in the range of C uint64_t.

REGTYPEc_uint8_list/1

Usage:c_uint8_list(List)

List is a list of c_uint8/1.

REGTYPEc_int_list/1

Usage:c_int_list(List)

List is a list of c_int/1.

REGTYPEc_double_list/1

Usage:c_double_list(List)

List is a list of c_double/1.

PROPERTYsize_of/3

Usage:size_of(Name,ListVar,SizeVar)

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

PROPERTYdo_not_free/2

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.

PROPERTYttr/3

Usage:ttr(Name,Var,TTr)

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

PROPERTYreturns/2

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.

PROPERTYneeds_ciao_ctx/1

Usage:needs_ciao_ctx(Name)

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

PROPERTYforeign/1

Usage:foreign(Name)

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

PROPERTYforeign/2

Usage:foreign(PrologName,ForeignName)

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

PROPERTYforeign_low/1

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.

PROPERTYforeign_low/2

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

DECLARATIONuse_foreign_source/1

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 should hold at call time:
(basic_props:atm_or_atm_list/1)Files is an atom or a list of atoms.

DECLARATIONuse_foreign_gluecode_header/1

Usage::- use_foreign_gluecode_header(Files).

Files is the (list of) alterantive headers that will be included in the glue-code file (instead of the default ciao_gluecode.h).

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

DECLARATIONuse_foreign_library/1

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

DECLARATIONuse_foreign_library/2

Usage::- use_foreign_library(OsArch,Libs).

Libs are the OS and architecture dependant libraries.

The following properties should 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.

DECLARATIONextra_compiler_opts/1

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

DECLARATIONextra_compiler_opts/2

Usage::- extra_compiler_opts(OsArch,Opts).

Opts are the OS and architecture dependant additional compiler options.

The following properties should 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.

DECLARATIONuse_compiler/1

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

DECLARATIONuse_compiler/2

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

DECLARATIONextra_linker_opts/1

Usage::- extra_linker_opts(Opts).

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

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

DECLARATIONextra_linker_opts/2

Usage::- extra_linker_opts(OsArch,Opts).

Opts are the OS and architecture dependant additional linker options.

The following properties should 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.

DECLARATIONuse_linker/1

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

DECLARATIONuse_linker/2

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

Documentation on imports

This module has the following direct dependencies:

Packages:
prelude, initial, condcomp, assertions, assertions/assertions_basic, regtypes.