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.

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 adress.

        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.

                    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.

                                                            Usage:c_uint8_list(List)

                                                            List is a list of c_uint8/1.

                                                              Usage:c_int_list(List)

                                                              List is a list of c_int/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 argument of type c_uint8_list/1, ListVar, is given by the argument of type integer SizeVar.

                                                                    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.

                                                                          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.

                                                                                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.

                                                                                  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

                                                                                    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

                                                                                    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.

                                                                                    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.

                                                                                    Usage::- use_foreign_library(OsArch,Libs).

                                                                                    Libs are the OS and architecture dependant libraries.

                                                                                    Usage::- extra_compiler_opts(Opts).

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

                                                                                    Usage::- extra_compiler_opts(OsArch,Opts).

                                                                                    Opts are the OS and architecture dependant additional compiler options.

                                                                                    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.

                                                                                    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.

                                                                                    Usage::- extra_linker_opts(Opts).

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

                                                                                    Usage::- extra_linker_opts(OsArch,Opts).

                                                                                    Opts are the OS and architecture dependant additional linker options.

                                                                                    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.

                                                                                    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.

                                                                                    DECLARATIONforeign_inline/2

                                                                                    Usage::- foreign_inline(Term,Text).

                                                                                    Term is a predicate name. Text is a source C code that define the predicate Term.

                                                                                    Documentation on imports

                                                                                    This module has the following direct dependencies:

                                                                                    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