PFM_$INTRO Domain/OS PFM_$INTRO
NAME
intro - managing faults
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/pfm.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/pfm.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/pfm.ins.ftn'
DESCRIPTION
The pfm_$ calls allow programs to manage signals, faults, and exceptions.
Programs can manage faults by establishing clean-up handlers and fault
handlers.
The following is a list of the pfm_$ calls.
pfm_$cleanup establish a clean-up handler
pfm_$enable enable asynchronous faults
pfm_$error_trap simulate a fault and save a traceback
pfm_$establish_fault_handler establish a fault handler
pfm_$inhibit inhibit asynchronous faults
pfm_$release_fault_handler release a fault handler
pfm_$reset_cleanup reset a clean-up handler
pfm_$rls_cleanup release clean-up handlers
pfm_$signal signal the calling process
Clean-up Handlers
A clean-up handler is a piece of code that ensures a program terminates
gracefully when it receives a fatal error. A clean-up handler begins
with a pfm_$cleanup call, and usually ends with a call to pfm_$signal or
pgm_$exit, though it can also simply continue back into the program after
the clean-up code.
A clean-up handler is not entered until all fault handlers established
for a fault have returned. If there is more than one established clean-
up handler for a program, the most recently established clean-up handler
is entered first, followed by the next most recently established clean-up
handler, and so on to the first established clean-up handler if neces-
sary.
There is a default clean-up handler invoked after all user-defined
handlers have completed. It releases any resources still held by the
program, before returning control to the process that invoked it.
Fault Handlers
A fault handler is a function supplied by the user that is called when a
fault occurs. When a fault occurs that has a handler established for it,
the system interrupts the faulted program and calls the designated fault
handler. When the fault handler returns, processing resumes where the
program was interrupted.
There are three types of fault handlers. By default a handler is called
only when a signal is received at the program level at which it was esta-
blished. A "multilevel" fault handler is called whenever a signal is
received at its or any subordinate program level. A "backstop" fault
handler is called only after all other non-backstop handers have
returned.
All fault handlers must take one argument of type pfm_$fault_rec_t and
return a value of type pfm_$fh_func_val_t, but their implementation is
otherwise left to the user. If there is more than one established
handler for a fault, the most recent nonbackstop handler is called first,
followed by the next most recent, if necessary, and so on until all the
applicable non-backstop handlers have returned. Then any backstop
handlers are called, if necessary, in the same last-established/first-
called order.
Constants
pfm_$all_faults
Passed to pfm_$establish_fault_hander to esablish a handler for all
possible faults.
Data Types
pfm_$cleanup_rec
A record type for passing process context among clean-up handler
calls. It is an opaque data type.
pfm_$fault_func_p_t
A pointer to a fault handler function.
pfm_$fault_rec_t
A record type for passing status information among fault handlers.
Only the status field is accessible to fault handler functions. The
following diagram illustrates the data type:
15 8 7 0
______________________________________________________________
| Not Used | pattern |
|_____________________________________________________________|
| status |
______________________________________________________________
15 0
pattern
Reserved for system use.
status
A fault status of type status_$t.
pfm_$fh_func_val_t
A value returned by a fault handler function. It specifies the
action to be taken when the handler completes. It can be one of the
following values:
pfm_$continue_fault_handling
Pass the fault to the next handler.
pfm_$return_to_faulting_code
Return control to the faulted program.
pfm_$fh_handle_t
A pointer to a fault handler function.
pfm_$fh_opt_set_t
A small set of options when establishing a fault handler. It can be
any combination of the following values:
pfm_$fh_multi_level
Establish a "multilevel" handler for faults encountered at the
current and all subordinate program levels.
pfm_$fh_backstop
Establish a "backstop" handler that is called after all non-
backstop handlers have been called.
By default, fault handlers are called consecutively on a last-
in/first-out basis, starting with the most recently established
handler and ending with the first fault handler established in
the current program level. To establish a default handler in
Pascal, pass an empty set [] for fh_options; in C, pass 0.
Errors
pfm_$bad_rls_order
Attempted to release a clean-up handler out of order.
pfm_$cleanup_not_found
There is no pending clean-up handler.
pfm_$cleanup_set
A clean-up handler was established successfully.
pfm_$cleanup_set_signalled
Attempted to use pfm_$cleanup_set as a signal.
pfm_$fh_not_found
Attempted to release non-existent fault handler.
pfm_$fh_wrong_level
Attempted to release fault handler at wrong level.
pfm_$invalid_cleanup_rec
Passed an invalid clean-up record to a call.
pfm_$no_space
Cannot allocate storage for a clean-up handler.
SEE ALSO
fault_$intro.