[ 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).

## See Also

catch / 3