[unix-history] / usr / lib / lisp / manual / ch10.r



                        CHAPTER  10


                     Exception Handling


   10.1.  Errset and Error Handler Functions

           FRANZ LISP allows the user to handle in a  number
      of  ways  the  errors  which arise during computation.
      One way is through the use of the _\be_\br_\br_\bs_\be_\bt function.  If
      an  error occurs during the evaluation of the _\be_\br_\br_\bs_\be_\bt's
      first argument, then the locus of control will  return
      to the errset which will return nil (except in special
      cases, such as _\be_\br_\br).  The other method of  error  han-
      dling  is  through an error handler function.  When an
      error occurs, the error handler is called and is given
      as  an argument a description  of the error which just
      occurred.  The error handler may take one of the  fol-
      lowing actions:

      (1)  it could take some drastic action like a _\br_\be_\bs_\be_\bt or
           a _\bt_\bh_\br_\bo_\bw.

      (2)  it could, assuming that the error is continuable,
           return  to  the function which noticed the error.
           The error handler  indicates  that  it  wants  to
           return a value from the error by returning a list
           whose _\bc_\ba_\br is the value it wants to return.

      (3)  it could decide  not  to  handle  the  error  and
           return a non-list to indicate this fact.


   10.2.  The Anatomy of an error

           Each error is described by a list of these items:

      (1)  error type - This is a symbol which indicates the
           general  classification of the error.  This clas-
           sification may determine which  function  handles
           this error.

      (2)  unique id - This  is  a  fixnum  unique  to  this
           error.

      (3)  continuable - If this is non-nil then this  error
           is  continuable.   There  are  some who feel that


Exception Handling                                      10-1


Exception Handling                                      10-2


           every error should be continuable and the  reason
           that some (in fact most) errors in FRANZ LISP are
           not continuable is due to  the  laziness  of  the
           programmers.

      (4)  message string - This is  a  symbol  whose  print
           name is  a message describing the error.

      (5)  data - There may  be  from  zero  to  three  lisp
           values   which   help  describe  this  particular
           error.  For example, the unbound  variable  error
           contains  one datum value, the symbol whose value
           is unbound.  The list describing that error might
           look like:
               (ER%misc 0 t |Unbound Variable:| foobar)


   10.3.  Error handling algorithm

           This is the sequence of operations which is  done
      when an error occurs:

      (1)  If the symbol ER%all has a  non  nil  value  then
           this  value is the name of an error handler func-
           tion.  That function is called with a description
           of  the  error.  If that function returns (and of
           course it may choose not to) and the value  is  a
           list  and  this  error  is  continuable,  then we
           return the _\bc_\ba_\br of the list to the function  which
           called  the error.  Presumably the function  will
           use this value to retry the  operation.   On  the
           other  hand,  if  the error handler returns a non
           list, then it  has  chosen  not  to  handle  this
           error,  so  we go on to step (2).  Something spe-
           cial happens before  we  call  the  ER%all  error
           handler which does not happen in any of the other
           cases we will describe  below.   To  help  insure
           that we don't get infinitely recursive errors  if
           ER%all is set to a bad value, the value of ER%all
           is set to nil before the handler is called.  Thus
           it is the responsibility of the ER%all handler to
           `reenable' itself by storing its name in ER%all.

      (2)  Next the specific error handler for the  type  of
           error  which  just  occurred  is  called  (if one
           exists) to see if it wants to handle  the  error.
           The  names of the handlers for the specific types
           of errors are stored as the values of the symbols
           whose  names  are  the  types.   For  example the
           handler for miscellaneous errors is stored as the
           value  of  ER%misc.   Of course, if ER%misc has a
           value of nil, then there is no error handler  for


                                      Printed: July 21, 1983


Exception Handling                                      10-3


           this  type of error.  Appendix B contains list of
           all error types.  The process of classifying  the
           errors  is  not complete and thus most errors are
           lumped into the ER%misc  category.   Just  as  in
           step  (1),  the error handler function may choose
           not to handle the error by returning a  non-list,
           and then we go to step (3).

      (3)  Next a check is made to see if there is an _\be_\br_\br_\bs_\be_\bt
           surrounding  this  error.  If so the second argu-
           ment to the  _\be_\br_\br_\bs_\be_\bt  call  is  examined.  If  the
           second  argument was not given or is non nil then
           the error message associated with this  error  is
           printed.   Finally   the  stack  is popped to the
           context of the _\be_\br_\br_\bs_\be_\bt and then the _\be_\br_\br_\bs_\be_\bt returns
           nil.  If there was no _\be_\br_\br_\bs_\be_\bt we go to step (4).

      (4)  If the symbol ER%tpl has a value then it  is  the
           name  of  an  error  handler which is called in a
           manner similar to that discussed  above.   If  it
           chooses  not  to  handle the error, we go to step
           (5).

      (5)  At this point it has  been  determined  that  the
           user doesn't want to handle this error.  Thus the
           error message is printed out and a _\br_\be_\bs_\be_\bt is  done
           to send the flow of control to the top-level.

           To summarize the error handling system:  When  an
      error occurs, you have two chances to handle it before
      the search for an _\be_\br_\br_\bs_\be_\bt is done.  Then, if  there  is
      no  _\be_\br_\br_\bs_\be_\bt,  you  have  one  more chance to handle the
      error before control jumps to the  top  level.   Every
      error  handler  works  in  the same way: It is given a
      description of the error (as described in the previous
      section).   It  may or may not return.  If it returns,
      then it returns either a list or a  non-list.   If  it
      returns  a list and the error is continuable, then the
      _\bc_\ba_\br of the list is  returned  to  the  function  which
      noticed  the  error.   Otherwise the error handler has
      decided not to handle the error and we go on to  some-
      thing else.


   10.4.  Default aids

           There are two standard error handlers  which will
      probably handle the needs of most users.  One of these
      is the lisp coded function _\bb_\br_\be_\ba_\bk-_\be_\br_\br-_\bh_\ba_\bn_\bd_\bl_\be_\br which  is
      the  default  value  of  ER%tpl.   Thus when all other
      handlers have ignored an error, _\bb_\br_\be_\ba_\bk-_\be_\br_\br-_\bh_\ba_\bn_\bd_\bl_\be_\br will
      take over.  It will print out the error message and go


                                      Printed: July 21, 1983


Exception Handling                                      10-4


      into a read-eval-print loop.  The other standard error
      handler   is   _\bd_\be_\bb_\bu_\bg-_\be_\br_\br-_\bh_\ba_\bn_\bd_\bl_\be_\br.    This  handler  is
      designed to be connected to  ER%alland  is  useful  if
      your  program  uses _\be_\br_\br_\bs_\be_\bt and you want to look at the
      error  before it is thrown up to the _\be_\br_\br_\bs_\be_\bt.


   10.5.  Autoloading

           When _\be_\bv_\ba_\bl, _\ba_\bp_\bp_\bl_\by or _\bf_\bu_\bn_\bc_\ba_\bl_\bl are told to  call  an
      undefined  function,  an  ER%undef  error is signaled.
      The default handler  for  this  error  is  _\bu_\bn_\bd_\be_\bf-_\bf_\bu_\bn_\bc-
      _\bh_\ba_\bn_\bd_\bl_\be_\br.   This  function  checks the property list of
      the undefined function for the indicator autoload.  If
      present,  the  value  of  that indicator should be the
      name of the file which contains the definition of  the
      undefined  function.  _\bU_\bn_\bd_\be_\bf-_\bf_\bu_\bn_\bc-_\bh_\ba_\bn_\bd_\bl_\be_\br will load the
      file and check if it has defined  the  function  which
      caused  the  error.  If it has, the error handler will
      return and the computation will  continue  as  if  the
      error did not occur.  This provides a way for the user
      to tell the lisp system about the location of commonly
      used functions.  The trace package sets up an autoload
      property to point to /usr/lib/lisp/trace.


   10.6.  Interrupt processing

           The  UNIX  operating  system  provides  one  user
      interrupt character which defaults to ^C.[]  The  user
      may  select  a  lisp function to run when an interrupt
      occurs.  Since this interrupt could occur at any time,
      and  in  particular  could  occur  at  a time when the
      internal stack pointers were in an inconsistent state,
      the processing of the interrupt may be delayed until a
      safe time.  When the first ^C is typed, the lisp  sys-
      tem  sets a flag that an interrupt has been requested.
      This flag is  checked at safe places within the inter-
      preter  and in the _\bq_\bl_\bi_\bn_\bk_\be_\br function.  If the lisp sys-
      tem doesn't respond to the first ^C, another ^C should
      be  typed.  This will cause all of the transfer tables
      to be cleared forcing all calls from compiled code  to
      go  through  the  _\bq_\bl_\bi_\bn_\bk_\be_\br function where the interrupt
      flag will  be  checked.   If  the  lisp  system  still
      doesn't  respond,  a  third ^C will cause an immediate
      interrupt.  This interrupt will not necessarily be  in
____________________
\e9   []Actually there are two but the lisp system does not al-
low you to catch the QUIT interrupt.


\e9                                      Printed: July 21, 1983


Exception Handling                                      10-5


      a safe place so the user should _\br_\be_\bs_\be_\bt the lisp  system
      as soon as possible.


\e9

\e9                                      Printed: July 21, 1983
Commit	Line	Data
f9a8037d C	1
	2
	3
	4
	5
	6
	7
	8	CHAPTER 10
	9
	10
	11	Exception Handling
	12
	13
	14
	15
	16
	17
	18	10.1. Errset and Error Handler Functions
	19
	20	FRANZ LISP allows the user to handle in a number
	21	of ways the errors which arise during computation.
	22	One way is through the use of the _\be_\br_\br_\bs_\be_\bt function. If
	23	an error occurs during the evaluation of the _\be_\br_\br_\bs_\be_\bt's
	24	first argument, then the locus of control will return
	25	to the errset which will return nil (except in special
	26	cases, such as _\be_\br_\br). The other method of error han-
	27	dling is through an error handler function. When an
	28	error occurs, the error handler is called and is given
	29	as an argument a description of the error which just
	30	occurred. The error handler may take one of the fol-
	31	lowing actions:
	32
	33	(1) it could take some drastic action like a _\br_\be_\bs_\be_\bt or
	34	a _\bt_\bh_\br_\bo_\bw.
	35
	36	(2) it could, assuming that the error is continuable,
	37	return to the function which noticed the error.
	38	The error handler indicates that it wants to
	39	return a value from the error by returning a list
	40	whose _\bc_\ba_\br is the value it wants to return.
	41
	42	(3) it could decide not to handle the error and
	43	return a non-list to indicate this fact.
	44
	45
	46
	47	10.2. The Anatomy of an error
	48
	49	Each error is described by a list of these items:
	50
	51	(1) error type - This is a symbol which indicates the
	52	general classification of the error. This clas-
	53	sification may determine which function handles
	54	this error.
	55
	56	(2) unique id - This is a fixnum unique to this
	57	error.
	58
	59	(3) continuable - If this is non-nil then this error
	60	is continuable. There are some who feel that
	61
	62
	63	Exception Handling 10-1
	64
65
66
67
68
69
70
71	Exception Handling 10-2
72
73
74	every error should be continuable and the reason
75	that some (in fact most) errors in FRANZ LISP are
76	not continuable is due to the laziness of the
77	programmers.
78
79	(4) message string - This is a symbol whose print
80	name is a message describing the error.
81
82	(5) data - There may be from zero to three lisp
83	values which help describe this particular
84	error. For example, the unbound variable error
85	contains one datum value, the symbol whose value
86	is unbound. The list describing that error might
87	look like:
88	(ER%misc 0 t \|Unbound Variable:\| foobar)
89
90
91
92	10.3. Error handling algorithm
93
94	This is the sequence of operations which is done
95	when an error occurs:
96
97	(1) If the symbol ER%all has a non nil value then
98	this value is the name of an error handler func-
99	tion. That function is called with a description
100	of the error. If that function returns (and of
101	course it may choose not to) and the value is a
102	list and this error is continuable, then we
103	return the _\bc_\ba_\br of the list to the function which
104	called the error. Presumably the function will
105	use this value to retry the operation. On the
106	other hand, if the error handler returns a non
107	list, then it has chosen not to handle this
108	error, so we go on to step (2). Something spe-
109	cial happens before we call the ER%all error
110	handler which does not happen in any of the other
111	cases we will describe below. To help insure
112	that we don't get infinitely recursive errors if
113	ER%all is set to a bad value, the value of ER%all
114	is set to nil before the handler is called. Thus
115	it is the responsibility of the ER%all handler to
116	`reenable' itself by storing its name in ER%all.
117
118	(2) Next the specific error handler for the type of
119	error which just occurred is called (if one
120	exists) to see if it wants to handle the error.
121	The names of the handlers for the specific types
122	of errors are stored as the values of the symbols
123	whose names are the types. For example the
124	handler for miscellaneous errors is stored as the
125	value of ER%misc. Of course, if ER%misc has a
126	value of nil, then there is no error handler for
127
128
129	Printed: July 21, 1983
130
131
132
133
134
135
136
137	Exception Handling 10-3
138
139
140	this type of error. Appendix B contains list of
141	all error types. The process of classifying the
142	errors is not complete and thus most errors are
143	lumped into the ER%misc category. Just as in
144	step (1), the error handler function may choose
145	not to handle the error by returning a non-list,
146	and then we go to step (3).
147
148	(3) Next a check is made to see if there is an _\be_\br_\br_\bs_\be_\bt
149	surrounding this error. If so the second argu-
150	ment to the _\be_\br_\br_\bs_\be_\bt call is examined. If the
151	second argument was not given or is non nil then
152	the error message associated with this error is
153	printed. Finally the stack is popped to the
154	context of the _\be_\br_\br_\bs_\be_\bt and then the _\be_\br_\br_\bs_\be_\bt returns
155	nil. If there was no _\be_\br_\br_\bs_\be_\bt we go to step (4).
156
157	(4) If the symbol ER%tpl has a value then it is the
158	name of an error handler which is called in a
159	manner similar to that discussed above. If it
160	chooses not to handle the error, we go to step
161	(5).
162
163	(5) At this point it has been determined that the
164	user doesn't want to handle this error. Thus the
165	error message is printed out and a _\br_\be_\bs_\be_\bt is done
166	to send the flow of control to the top-level.
167
168	To summarize the error handling system: When an
169	error occurs, you have two chances to handle it before
170	the search for an _\be_\br_\br_\bs_\be_\bt is done. Then, if there is
171	no _\be_\br_\br_\bs_\be_\bt, you have one more chance to handle the
172	error before control jumps to the top level. Every
173	error handler works in the same way: It is given a
174	description of the error (as described in the previous
175	section). It may or may not return. If it returns,
176	then it returns either a list or a non-list. If it
177	returns a list and the error is continuable, then the
178	_\bc_\ba_\br of the list is returned to the function which
179	noticed the error. Otherwise the error handler has
180	decided not to handle the error and we go on to some-
181	thing else.
182
183
184
185	10.4. Default aids
186
187	There are two standard error handlers which will
188	probably handle the needs of most users. One of these
189	is the lisp coded function _\bb_\br_\be_\ba_\bk-_\be_\br_\br-_\bh_\ba_\bn_\bd_\bl_\be_\br which is
190	the default value of ER%tpl. Thus when all other
191	handlers have ignored an error, _\bb_\br_\be_\ba_\bk-_\be_\br_\br-_\bh_\ba_\bn_\bd_\bl_\be_\br will
192	take over. It will print out the error message and go
193
194
195	Printed: July 21, 1983
196
197
198
199
200
201
202
203	Exception Handling 10-4
204
205
206	into a read-eval-print loop. The other standard error
207	handler is _\bd_\be_\bb_\bu_\bg-_\be_\br_\br-_\bh_\ba_\bn_\bd_\bl_\be_\br. This handler is
208	designed to be connected to ER%alland is useful if
209	your program uses _\be_\br_\br_\bs_\be_\bt and you want to look at the
210	error before it is thrown up to the _\be_\br_\br_\bs_\be_\bt.
211
212
213
214	10.5. Autoloading
215
216	When _\be_\bv_\ba_\bl, _\ba_\bp_\bp_\bl_\by or _\bf_\bu_\bn_\bc_\ba_\bl_\bl are told to call an
217	undefined function, an ER%undef error is signaled.
218	The default handler for this error is _\bu_\bn_\bd_\be_\bf-_\bf_\bu_\bn_\bc-
219	_\bh_\ba_\bn_\bd_\bl_\be_\br. This function checks the property list of
220	the undefined function for the indicator autoload. If
221	present, the value of that indicator should be the
222	name of the file which contains the definition of the
223	undefined function. _\bU_\bn_\bd_\be_\bf-_\bf_\bu_\bn_\bc-_\bh_\ba_\bn_\bd_\bl_\be_\br will load the
224	file and check if it has defined the function which
225	caused the error. If it has, the error handler will
226	return and the computation will continue as if the
227	error did not occur. This provides a way for the user
228	to tell the lisp system about the location of commonly
229	used functions. The trace package sets up an autoload
230	property to point to /usr/lib/lisp/trace.
231
232
233
234	10.6. Interrupt processing
235
236	The UNIX operating system provides one user
237	interrupt character which defaults to ^C.[] The user
238	may select a lisp function to run when an interrupt
239	occurs. Since this interrupt could occur at any time,
240	and in particular could occur at a time when the
241	internal stack pointers were in an inconsistent state,
242	the processing of the interrupt may be delayed until a
243	safe time. When the first ^C is typed, the lisp sys-
244	tem sets a flag that an interrupt has been requested.
245	This flag is checked at safe places within the inter-
246	preter and in the _\bq_\bl_\bi_\bn_\bk_\be_\br function. If the lisp sys-
247	tem doesn't respond to the first ^C, another ^C should
248	be typed. This will cause all of the transfer tables
249	to be cleared forcing all calls from compiled code to
250	go through the _\bq_\bl_\bi_\bn_\bk_\be_\br function where the interrupt
251	flag will be checked. If the lisp system still
252	doesn't respond, a third ^C will cause an immediate
253	interrupt. This interrupt will not necessarily be in
254	____________________
255	\e9 []Actually there are two but the lisp system does not al-
256	low you to catch the QUIT interrupt.
257
258
259
260	\e9 Printed: July 21, 1983
261
262
263
264
265
266
267
268	Exception Handling 10-5
269
270
271	a safe place so the user should _\br_\be_\bs_\be_\bt the lisp system
272	as soon as possible.
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323	\e9
324
325	\e9 Printed: July 21, 1983
326
327
328