NAME

exceptions - tile kernel error handling functions

SYNOPSIS

forth

DESCRIPTION

The
tile
kernel word set for support of exception definition and management.
Exceptions may be signaled by the environment (such as arithmetic
or memory segmentation error) or raised by functions in an application.
The
tile
forth virtual machine maintains exception frames. An exception frame
is a copy of the state of the virtual machine when a colon definition
with error handling is entered. This state may be used to restore the
virtual machine when an error occurs.

An exception block is part of a colon definition and marked in a
syntax style similar to the high level management block "does>". This
block will receive the error flag (signal or exception) and the machine
is restored if an error occurs. Exception blocks may be nested. A
function with error handling may call functions with error handling
and so on. The cost of an error handling block corresponds to the cost
of saving all virtual machine registers in an exception block on the
return stack.

Exceptions should be used to simplify control structures where the
programmer is otherwise forced to mix the control structure for the
algorithm with the control structure for the error situations.

code exception ( --- )

Used in the following form:

exception<exception-name>(--exception)
to define an exception symbol. An exception may be raised using:
<exception-name>raise
The defined "exception" returns a pointer to the entry on the parameter
stack when used and may be directly displayed with the word ".name".

code exception> ( [signal] or [exception] -- ) compilation immediate

Used within a colon definition to mark the beginning of the
exception section of the definition:

:<name>(...)...<colon-definition>...exception> ( [signal] or [exception] -- )
...<error-handling>...;
If an error occurs or an "exception" is raised during the
execution of the code definition section the control is past
to the latest exception block, and the signal number or the
exception is past as a parameter. The status of the stacks are
restored to the situation before the execution of the most recent
definition with an exception block. To pass the exception upwards,
to the next exception block, the function "raise" should be used.

vocabulary exceptions ( -- )

Vocabulary containing the exception management definitions.
Allows definitions of forth level capturing of errors. Uses
a syntax style similar Ada to make the beginning of an exception
section within a colon definition. Include into the vocabulary
search structure, "context", to allow access of these extensions.

code raise ( [signal] or [exception] -- )

Activates a exceptions handler with signal identification number
or an exception symbol. If an exception frame exists the virtual
machine is restored to this state and resumed. The default action
taken if no exception block is available is abort with a message
about the task, and the name of the signal or exception. Signals
are generated from the run-time environment.

INTERNALS

The following words of the exception extension are mainly used to
implement the error handling mechanism.

code (exception;) ( -- ) compilation

Unlinks the current exception frame from the return stack and
returns from a colon definition. Compiled by the word "exception>".

code (exception>) ( addr -- ) compilation

Builds an exception frame on the return stack and jumps to the
address given as a parameter, "addr". A colon definition with
an exception block will have a "code" field with a pointer to
code section with this word. The virtual machine will push a
pointer to the parameter field, "addr", and call the exception
section.

code (exceptionunlink;) ( -- ) compilation

Unlinks the exception frame and argument frame from the stacks
and returns from the colon definitions. Compiled by the word
"exception>" when a local frame has been used.

SEE ALSO

tile(1),forth(3X).

EXAMPLES

An example showing how to redefine the arithmetic division operation
for exception and retry:

NOTE

The function list is sorted in ASCII order. The type and mode
of the entry is indicated together with the parameter stack effect.

COPYING

Copyright (C) 1990 Mikael R.K. Patel

Permission is granted to make and distribute verbatim copies
of this manual provided the copyright notice and this permission
notice are preserved on all copies.

Permission is granted to copy and distribute modified versions
of this manual under the conditions for verbatim copying,
provided also that the section entitled "GNU General Public
License" is included exactly as in the original, and provided
that the entire resulting derived work is distributed under
the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of
this manual into another language, under the above conditions
for modified versions, except that the section entitled "GNU
General Public License" may be included in a translation approved
by the author instead of in the original English.