Exception and Signal handling

Author(s): The CLIP Group.

This module includes predicates related to exceptions and signals, which alter the normal flow of Prolog.

Usage and interface

Documentation on exports

PREDICATE
catch(Goal,Error,Handler)

Executes Goal. If an exception is raised during its execution, Error is unified with the exception, and if the unification succeeds, the entire execution derived from Goal is aborted, and Handler is executed. The execution resumes with the continuation of the catch/3 call. For example, given the code

p(X) :- throw(error), display('---').
p(X) :- display(X).
the execution of "catch(p(0), E, display(E)), display(.), fail." results in the output "error.".

(Trust) Usage:ISO

  • Calls should, and exit will be compatible with:
    (basic_props:term/1)Error is any term.
    (basic_props:callable/1)Handler is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold at call time:
    (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
  • The following properties hold upon exit:
    (basic_props:term/1)Error is any term.
    (basic_props:callable/1)Handler is a term which represents a goal, i.e., an atom or a structure.
  • The following properties hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.
Meta-predicate with arguments: catch(goal,?,goal).

PREDICATE
intercept(Goal,Signal,Handler)

Executes Goal. If a signal is sent during its execution, Signal is unified with the exception, and if the unification succeeds, Handler is executed and then the execution resumes after the point where the exception was thrown. To avoid infinite loops if Handler raises an exception which unifies with Error, the exception handler is deactivated before executing Handler. Note the difference with builtin catch/3, given the code

p(X) :- send_signal(signal), display('---').
p(X) :- display(X).
the execution of "intercept(p(0), E, display(E)), display(.), fail." results in the output "error---.0.".

Usage:

  • Call and exit should be compatible with:
    (basic_props:term/1)Signal is any term.
  • The following properties should hold at call time:
    (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    (basic_props:callable/1)Handler is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold upon exit:
    (basic_props:term/1)Signal is any term.
Meta-predicate with arguments: intercept(goal,?,goal).
General properties:

Test:intercept(G,S,H)

intercept/3 preserves determinism properties of Goal (even when H and G share variables)

  • If the following properties should hold at call time:
    (term_basic:= /2)term_basic:G=((A=a;A=b),send_signal(c(A)))
    (term_basic:= /2)term_basic:S=c(A)
    (term_basic:= /2)term_basic:H=display(A)
    then the following properties should hold globally:
    (native_props:not_fails/1)All the calls of the form intercept(G,S,H) do not fail.
    (native_props:non_det/1)All calls of the form intercept(G,S,H) are non-deterministic.

PREDICATE
throw(Ball)

Raises an error, throwing the exception Ball, to be caught by an ancestor catch/3. The closest matching ancestor is chosen. In addition to calls to throw/2 in user code, exceptions are also thrown by many library predicates in cases of error.

(Trust) Usage:ISOthrow(Term)

  • The following properties should hold at call time:
    (term_typing:nonvar/1)Term is currently a term which is not a free variable.

PREDICATE
send_signal(Signal)

Emits a signal, to be intercepted by an ancestor intercept/3. The closest matching ancestor is chosen. If the signal is not intercepted, the following error is thrown: error(unintercepted_signal(Signal), send_signal/1-1).

(Trust) Usage:send_signal(Term)

  • The following properties should hold at call time:
    (term_typing:nonvar/1)Term is currently a term which is not a free variable.

PREDICATE
send_silent_signal(Signal)

Emits a signal as send_signal/1, but do not throws an error if the signal is not intercepted (i.e. just suceeds silently)

(Trust) Usage:send_silent_signal(Term)

  • The following properties should hold at call time:
    (term_typing:nonvar/1)Term is currently a term which is not a free variable.

PREDICATE
halt

Halt the system, exiting to the invoking shell.

Usage:ISO

  • The following properties should hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.

PREDICATE
halt(Code)

Halt the system, exiting to the invoking shell, returning exit code Code.

Usage:ISO

  • The following properties should hold at call time:
    (basic_props:int/1)Code is an integer.
  • The following properties should hold upon exit:
    (basic_props:int/1)Code is an integer.

PREDICATE
abort

Abort the current execution.

Known bugs and planned improvements

  • Run-time checks have been reported not to work with this code. That means that either the assertions here, or the code that implements the run-time checks are erroneous.