Foreign Function Interface

The Prolog interpreter provides an internal API that allows defining built-in predicates and evaluable functions. This internal API is not public available since it is an unsafe API. The API is based on passing directly the skeleton and display data structures which could then potentially be modified by client code and make the Prolog interpreter unusable. On the other hand the internal API allows realizing fast built-ins with a broad functionality.

For less time critical and specialized predicates and evaluable functions we provide an external API here. This API consists of the already described interpreter, knowledgebase, term and special objects. The main use cases are call-in and call-out. In this section we explain in more detail which automatic call-out mechanisms are provided by the Prolog interpreter. The call-out mechanism is based on associating a knowledge base member with a Java class member.

On the knowledge base side the members can be either predicates or evaluable functions. When using the foreign_XX/3 directive the application programmer can freely choose a name for a predicate or an evaluable function. It is also possible to use qualified names and/or to place foreign_XX/3 directives inside a module. The necessary arity depends on the associated Java class member. Among the Java class members we find Constructors, Methods and Fields. Only public members are accepted, and setter Field member must not be final.

Table 2: Java Class Arguments
Knowledge Base Class Member Parameter Types Return Type
Predicate


Constructor Constructor <Constructor Paras> <Declared Class>
Method Method <Method Paras> <Method Return>
Getter Field None <Field Type>
Setter Field <Field Type> Void
Evaluable Function



Function Method <Method Paras> <Method Return>
Constant Field None Field Type

A parameter type of the Java class member of type Interpreter or CallOut is not counted. All other parameter types are counted as an input Prolog argument. If the Java class member is non-static then the knowledge base member has an additional input Prolog argument in the first position which will be a reference to the receiver object. If the Java class member has a return type then the knowledge base member has an addition output Prolog argument in the last position.

The parameter types determine the de-normalization applied to the input Prolog argument before calling the Java class member. Evaluable function input arguments are first evaluated before the de-normalization. The return type determines the normalization applied to the Java value before unifying with the output Prolog argument. If the Java class member throws an exception during invocation the exception is mapped to a Prolog term and this error is further thrown by the Prolog interpreter.

Table 3: Java Array Class Arguments
Knowledge Base Parameter Types Return Type
Predicate

Dimension int <Declared Class>
Element int <Component Type>
Update int, <Component Type> Void
Evaluable Function


Length None int
Member int <Component Type>

With release 1.1.2 it is also possible to register delegates for Java array classes. Except for the constructor these delegates expect the array instance as a receiver object. The delegates use the component type of the Java array class to determine the desired de-normalization and normalization. The same component types are supported as for the parameters types and return type of Java class members.

Comments