Class CallOut

This class represents a call-out. Call-out objects cannot be directly constructed by the application programmer. A call-out object is created by the interpreter and passed to a foreign predicate if it has such a parameter.

Foreign predicates can be programmatically registered via the method defineForeign() of the Interpreter class in the programming interface or by invoking the built-in foreign/3. The accepted formal parameters and their interpretation are listed in the language reference documentation. A formal parameter of type Interpreter is needed for foreign predicate that change variable bindings. A formal parameter of type CallOut is needed for non-deterministic foreign predicates.

The API of the CallOut allows fine control of choice points. Via the method getFirst() the foreign predicate can query whether it was called for the first time. Via the method setRetry() the foreign predicate can indicate that it desires a choice point. The methods setData() and getData() can be used to access client data in the choice point.

In case a choice point was desired the foreign predicate can additionally indicate via the method setCutter() whether it desires to be notified when the choice point is cleaned up. Choice points are cleaned up by the interpreter when a cut occurs in the continuation, when an exception occurs in the continuation or when the search is externally terminated. Via the method getCleanup() the foreign predicate can query whether it is called for a clean-up.

During a clean-up the foreign predicate can query the current exception via the method getException(). If needed it can then accumulated further exceptions and store the new current exception via the method setException().

By default the interpreter does barrier handling for non-deterministic foreign predicates. This includes invoking markFrame() prior to invoking a foreign predicate and then when the predicate succeeds swapBarrier (). This also includes invoking swapBarrier() and releaseFrame() upon redo of the foreign predicate. Finally this also includes invoking swapBarrier() during a clean-up for foreign predicates with a cutter. The method setSpecial() allows switching off this default barrier handling.


public final class CallOut {
    public boolean getFirst();
    public boolean getCleanup();
public void setRetry(boolean r);
    public void setCutter(boolean c);
    public void setSpecial(boolean c);

    public Object getData();
public void setData(Object o);
    public InterpreterException getException();
public void setException(InterpreterException e);