runtime/error.h

   1 /*
   2  * Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25
  26 /*
  27     error.h
  28
  29     This file defines the interface to the exception raising scheme.
  30
  31     Copyright (c) 1988-1996 NeXT Software, Inc. as an unpublished work.
  32     All rights reserved.
  33 */
  34
  35 #warning The API in this header is obsoleted by NSException et al.
  36
  37 #ifndef _OBJC_ERROR_H_
  38 #define _OBJC_ERROR_H_
  39
  40 #include <setjmp.h>
  41 #import <objc/objc-api.h>
  42
  43
  44 typedef struct _NXHandler {     /* a node in the handler chain */
  45     jmp_buf jumpState;                  /* place to longjmp to */
  46     struct _NXHandler *next;            /* ptr to next handler */
  47     int code;                           /* error code of exception */
  48     const void *data1, *data2;          /* blind data for describing error */
  49 } NXHandler;
  50
  51
  52 /* Handles RAISE's with nowhere to longjmp to */
  53 typedef void NXUncaughtExceptionHandler(int code, const void *data1,
  54                                                 const void *data2);
  55 OBJC_EXPORT NXUncaughtExceptionHandler *_NXUncaughtExceptionHandler;
  56 #define NXGetUncaughtExceptionHandler() _NXUncaughtExceptionHandler
  57 #define NXSetUncaughtExceptionHandler(proc) \
  58                         (_NXUncaughtExceptionHandler = (proc))
  59
  60 /* NX_DURING, NX_HANDLER and NX_ENDHANDLER are always used like:
  61
  62         NX_DURING
  63             some code which might raise an error
  64         NX_HANDLER
  65             code that will be jumped to if an error occurs
  66         NX_ENDHANDLER
  67
  68    If any error is raised within the first block of code, the second block
  69    of code will be jumped to.  Typically, this code will clean up any
  70    resources allocated in the routine, possibly case on the error code
  71    and perform special processing, and default to RERAISE the error to
  72    the next handler.  Within the scope of the handler, a local variable
  73    called NXLocalHandler of type NXHandler holds information about the
  74    error raised.
  75
  76    It is illegal to exit the first block of code by any other means than
  77    NX_VALRETURN, NX_VOIDRETURN, or just falling out the bottom.
  78  */
  79
  80 /* private support routines.  Do not call directly. */
  81 OBJC_EXPORT void _NXAddHandler( NXHandler *handler );
  82 OBJC_EXPORT void _NXRemoveHandler( NXHandler *handler );
  83
  84 #define NX_DURING { NXHandler NXLocalHandler;                   \
  85                     _NXAddHandler(&NXLocalHandler);             \
  86                     if( !_setjmp(NXLocalHandler.jumpState) ) {
  87
  88 #define NX_HANDLER _NXRemoveHandler(&NXLocalHandler); } else {
  89
  90 #define NX_ENDHANDLER }}
  91
  92 #define NX_VALRETURN(val)  do { typeof(val) temp = (val);       \
  93                         _NXRemoveHandler(&NXLocalHandler);      \
  94                         return(temp); } while (0)
  95
  96 #define NX_VOIDRETURN   do { _NXRemoveHandler(&NXLocalHandler); \
  97                         return; } while (0)
  98
  99 /* RAISE and RERAISE are called to indicate an error condition.  They
 100    initiate the process of jumping up the chain of handlers.
 101  */
 102
 103 OBJC_EXPORT
 104 #if defined(__GNUC__) && !defined(__STRICT_ANSI__)
 105     volatile    /* never returns */
 106 #endif
 107 void _NXRaiseError(int code, const void *data1, const void *data2)
 108 #if defined(__GNUC__)
 109   __attribute__ ((noreturn))
 110 #endif
 111 ;
 112
 113 #define NX_RAISE( code, data1, data2 )  \
 114                 _NXRaiseError( (code), (data1), (data2) )
 115
 116 #define NX_RERAISE()    _NXRaiseError( NXLocalHandler.code,     \
 117                                 NXLocalHandler.data1, NXLocalHandler.data2 )
 118
 119 /* These routines set and return the procedure which is called when
 120    exceptions are raised.  This procedure must NEVER return.  It will
 121    usually either longjmp, or call the uncaught exception handler.
 122    The default exception raiser is also declared
 123  */
 124 typedef volatile void NXExceptionRaiser(int code, const void *data1, const void *data2);
 125 OBJC_EXPORT void NXSetExceptionRaiser(NXExceptionRaiser *proc);
 126 OBJC_EXPORT NXExceptionRaiser *NXGetExceptionRaiser(void);
 127 OBJC_EXPORT NXExceptionRaiser NXDefaultExceptionRaiser;
 128
 129
 130 /* The error buffer is used to allocate data which is passed up to other
 131    handlers.  Clients should clear the error buffer in their top level
 132    handler.  The Application Kit does this.
 133  */
 134 OBJC_EXPORT void NXAllocErrorData(int size, void **data);
 135 OBJC_EXPORT void NXResetErrorData(void);
 136
 137 #endif /* _OBJC_ERROR_H_ */