Class CallIn

The call-in object can be obtained from an interpreter by providing optionally a goal and optionally a result by the iterator() methods. A call-in object is needed to interact with choice points and variable bindings. Thus call-in objects are needed when Prolog goals are called. The application programmer cannot subclass the call-in class.

The method hasNext() can be used check whether the interactor can be advanced. Initially the interactor is positioned before the first solution. The method next() effectively advances the interactor. The method throws a directive failed error when there was no solution. The method close() closes an interactor when there were still elements.

The method getNondet() allows checking whether there are choices and potentially further solutions. Further solutions can be prevented by calling the method cut() which will remove choice points. An alternative way to close an interactor is to use the method cleanup(), which takes an initial exception while closing.

It is possible to use call-in objects to implement meta-predicates, provide the special directive is given to the CallOut argument. But because separate choice points and tail recursion barrier are created for invoked goals, it is not possible to program cut transparent arguments for meta-predicates this way.

Inside the Prolog execution of hasNext() or next() or when these methods have been complet-ed during Java execution it is allowed to create and use further call-in objects, as long as the interaction with these objects is complete. For non-stack use call-in objects have to be drawn from forked interpreters inside the same thread.


public final class CallIn {
public boolean hasNext() throws InterpreterException;
public CallIn next() throws InterpreterMessage, InterpreterException;
public void close() throws InterpreterException;

public boolean getNondet();
public void cut() throws InterpreterException;
public InterpreterException cleanup(InterpreterException x);