shithub: purgatorio

ref: 6b84c3a6548f1c577948763b0a09a7b6e2460e04
dir: purgatorio/man/2/exception

.TH EXCEPTION 2
.SH NAME
exception \- obtain data about exceptions and set exception-handling modes
.SH SYNOPSIS
.EX
include "exception.m";
exc := load Exception Exception->PATH;

NOTIFYLEADER, PROPAGATE: con iota;

getexc:	fn(pid: int): (int, string, string);
setexcmode:	fn(mode: int): int;
.EE
.SH DESCRIPTION
.B Exception
provides functions to fetch data about exceptions in other processes
and change exception-handling modes.
It encapsulates exception-related operations on files in
.IR prog (3).
.PP
When a process incurs an exception, the system saves details before processing the exception,
following Limbo's rules.
.B Getexc
returns a tuple
.BI ( pc,\ module,\ description )
that describes the most recent exception raised in process
.IR pid .
(A process id of -1 is taken to mean the current process.)
The tuple contains the pc value, the module name, and the exception name.
The value
.B "(0,\ nil,\ nil)"
is returned if no exception has occurred.
.PP
By default, when a process incurs an exception that is not handled —
no
.B exception
clause matches that exception —
the process is stopped in a `Broken' state for debugging,
and the exception does not propagate further.
.B Setexcmode
changes the way that the system handles exceptions for the current process
and those it later spawns.
A
.I mode
of
.BR NOTIFYLEADER
makes the invoking process the leader of the
current process group for exception handling.
Subsequently, an exception in any process in the current process group
will atomically destroy all processes in the group except the leader,
and the exception will be raised in the leader.
(This works even when the leader itself incurs the exception.)
A
.I mode
of
.B PROPAGATE
instead causes an exception in any process in the group to be raised in
all processes in the group, allowing them all to initiate local error recovery
(ie, within each process).
.SH SOURCE
.B /appl/lib/exception.b
.SH DIAGNOSTICS
Both functions return -1 on error and set the system error string.
.SH SEE ALSO
.IR prog (3)