runtime/error.h

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