runtime/error.h

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