[ Control | Reference Manual | Alphabetic Index ]

throw(+Ball)

Throw an exception described by Ball. Continue execution at the recovery procedure of a matching ancestor catch/3

Ball: Any term, but no variable

Description

This predicate neither succeeds nor fails, but raises (or "throws") an exception identified by the term Ball. Execution will then continue with the Recovery goal of the innermost catch/3 ancestor that catches this exception (i.e., whose second argument, the Catcher, unifies with Ball).

If the exception is not caught by any catch/3 in the user program, then

in a development system with a toplevel, the exception will be caught by the toplevel, reporting an 'uncaught exception' (230) error.
in a standalone ECLiPSe without toplevel (e.g. using the -e command line option), the process will exit with exit code 2.
in an embeddded system, control will return to the host program with a corresponding return code (PTHROW, EC_throw, etc).

The term that is unified with the ancestor's Catcher is a copy of the Ball, i.e. if it contains variables, these are not identical to the original ones in Ball.

NOTE: block/3 is a deprecated alias for catch/3, and behaves identically. exit_block/1 is a deprecated alias for throw/1, and behaves identically.

Modes and Determinism

throw(+) is erroneous

Exceptions

(4) instantiation fault: Ball is uninstantiated.
(230) uncaught exception: Ball does not unify with a Catcher of any uncompleted call of catch/3.

Examples

      % A variable Catcher catches all throws
      ?- catch(throw(hello), T, writeln(recover(T))).
      recover(hello)
      T = hello
      Yes (0.00s cpu)


      % An instantiated Catcher catches only matching throws
      ?- catch(throw(hello), hello, writeln(recovered)).
      recovered
      Yes (0.00s cpu)

      ?- catch(throw(hello), world, writeln(recovered)).
      uncaught exception in throw(hello)
      Abort


      % A partially instantiated Catcher catches only matching throws
      ?- catch(throw(hello(world)), hello(Who), writeln(recovered(Who))).
      recovered(world)
      Yes (0.00s cpu)

      ?- catch(throw(hi(world)), hello(Who), writeln(recovered(Who))).
      uncaught exception in throw(hi(world))
      Yes (0.00s cpu)


      % The caught term is a copy of the thrown term (fresh variables)
      ?- T1=f(X), catch(throw(T1), T2, true), variant(T1, T2), T1\==T2.
      T1 = f(X_88)
      T2 = f(X_510)
      Yes (0.00s cpu)

Error:
      throw(_).                (Error 4).
      throw(never_caught).     (Error 230).

throw(+Ball)

Description

Modes and Determinism

Exceptions

Examples

See Also