headers/libs/libcxxrt/cxxabi.h

   1 /*
   2  * Copyright 2012 David Chisnall. All rights reserved.
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a copy
   5  * of this software and associated documentation files (the "Software"), to
   6  * deal in the Software without restriction, including without limitation the
   7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
   8  * sell copies of the Software, and to permit persons to whom the Software is
   9  * furnished to do so, subject to the following conditions:
  10  *
  11  * The above copyright notice and this permission notice shall be
  12  * included in all copies or substantial portions of the Software.
  13  *
  14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  15  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  17  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  18  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  19  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  20  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21  */
  22
  23 #ifndef __CXXABI_H_
  24 #define __CXXABI_H_
  25 #include <stddef.h>
  26 #include <stdint.h>
  27 #include "unwind.h"
  28 namespace std
  29 {
  30         class type_info;
  31 }
  32 /*
  33  * The cxxabi.h header provides a set of public definitions for types and
  34  * functions defined by the Itanium C++ ABI specification.  For reference, see
  35  * the ABI specification here:
  36  *
  37  * http://sourcery.mentor.com/public/cxx-abi/abi.html
  38  *
  39  * All deviations from this specification, unless otherwise noted, are
  40  * accidental.
  41  */
  42
  43 #ifdef __cplusplus
  44 namespace __cxxabiv1 {
  45 extern "C" {
  46 #endif
  47 /**
  48  * Function type to call when an unexpected exception is encountered.
  49  */
  50 typedef void (*unexpected_handler)();
  51 /**
  52  * Function type to call when an unrecoverable condition is encountered.
  53  */
  54 typedef void (*terminate_handler)();
  55
  56
  57 /**
  58  * Structure used as a header on thrown exceptions.  This is the same layout as
  59  * defined by the Itanium ABI spec, so should be interoperable with any other
  60  * implementation of this spec, such as GNU libsupc++.
  61  *
  62  * This structure is allocated when an exception is thrown.  Unwinding happens
  63  * in two phases, the first looks for a handler and the second installs the
  64  * context.  This structure stores a cache of the handler location between
  65  * phase 1 and phase 2.  Unfortunately, cleanup information is not cached, so
  66  * must be looked up in both phases.  This happens for two reasons.  The first
  67  * is that we don't know how many frames containing cleanups there will be, and
  68  * we should avoid dynamic allocation during unwinding (the exception may be
  69  * reporting that we've run out of memory).  The second is that finding
  70  * cleanups is much cheaper than finding handlers, because we don't have to
  71  * look at the type table at all.
  72  *
  73  * Note: Several fields of this structure have not-very-informative names.
  74  * These are taken from the ABI spec and have not been changed to make it
  75  * easier for people referring to to the spec while reading this code.
  76  */
  77 struct __cxa_exception
  78 {
  79 #if __LP64__
  80         /**
  81          * Reference count.  Used to support the C++11 exception_ptr class.  This
  82          * is prepended to the structure in 64-bit mode and squeezed in to the
  83          * padding left before the 64-bit aligned _Unwind_Exception at the end in
  84          * 32-bit mode.
  85          *
  86          * Note that it is safe to extend this structure at the beginning, rather
  87          * than the end, because the public API for creating it returns the address
  88          * of the end (where the exception object can be stored).
  89          */
  90         uintptr_t referenceCount;
  91 #endif
  92         /** Type info for the thrown object. */
  93         std::type_info *exceptionType;
  94         /** Destructor for the object, if one exists. */
  95         void (*exceptionDestructor) (void *);
  96         /** Handler called when an exception specification is violated. */
  97         unexpected_handler unexpectedHandler;
  98         /** Hander called to terminate. */
  99         terminate_handler terminateHandler;
 100         /**
 101          * Next exception in the list.  If an exception is thrown inside a catch
 102          * block and caught in a nested catch, this points to the exception that
 103          * will be handled after the inner catch block completes.
 104          */
 105         __cxa_exception *nextException;
 106         /**
 107          * The number of handlers that currently have references to this
 108          * exception.  The top (non-sign) bit of this is used as a flag to indicate
 109          * that the exception is being rethrown, so should not be deleted when its
 110          * handler count reaches 0 (which it doesn't with the top bit set).
 111          */
 112         int handlerCount;
 113 #if defined(__arm__) && !defined(__ARM_DWARF_EH__)
 114         /**
 115          * The ARM EH ABI requires the unwind library to keep track of exceptions
 116          * during cleanups.  These support nesting, so we need to keep a list of
 117          * them.
 118          */
 119         _Unwind_Exception *nextCleanup;
 120         /**
 121          * The number of cleanups that are currently being run on this exception.
 122          */
 123         int cleanupCount;
 124 #endif
 125         /**
 126          * The selector value to be returned when installing the catch handler.
 127          * Used at the call site to determine which catch() block should execute.
 128          * This is found in phase 1 of unwinding then installed in phase 2.
 129          */
 130         int handlerSwitchValue;
 131         /**
 132          * The action record for the catch.  This is cached during phase 1
 133          * unwinding.
 134          */
 135         const char *actionRecord;
 136         /**
 137          * Pointer to the language-specific data area (LSDA) for the handler
 138          * frame.  This is unused in this implementation, but set for ABI
 139          * compatibility in case we want to mix code in very weird ways.
 140          */
 141         const char *languageSpecificData;
 142         /** The cached landing pad for the catch handler.*/
 143         void *catchTemp;
 144         /**
 145          * The pointer that will be returned as the pointer to the object.  When
 146          * throwing a class and catching a virtual superclass (for example), we
 147          * need to adjust the thrown pointer to make it all work correctly.
 148          */
 149         void *adjustedPtr;
 150 #if !__LP64__
 151         /**
 152          * Reference count.  Used to support the C++11 exception_ptr class.  This
 153          * is prepended to the structure in 64-bit mode and squeezed in to the
 154          * padding left before the 64-bit aligned _Unwind_Exception at the end in
 155          * 32-bit mode.
 156          *
 157          * Note that it is safe to extend this structure at the beginning, rather
 158          * than the end, because the public API for creating it returns the address
 159          * of the end (where the exception object can be stored)
 160          */
 161         uintptr_t referenceCount;
 162 #endif
 163         /** The language-agnostic part of the exception header. */
 164         _Unwind_Exception unwindHeader;
 165 };
 166
 167 /**
 168  * ABI-specified globals structure.  Returned by the __cxa_get_globals()
 169  * function and its fast variant.  This is a per-thread structure - every
 170  * thread will have one lazily allocated.
 171  *
 172  * This structure is defined by the ABI, so may be used outside of this
 173  * library.
 174  */
 175 struct __cxa_eh_globals
 176 {
 177         /**
 178          * A linked list of exceptions that are currently caught.  There may be
 179          * several of these in nested catch() blocks.
 180          */
 181         __cxa_exception *caughtExceptions;
 182         /**
 183          * The number of uncaught exceptions.
 184          */
 185         unsigned int uncaughtExceptions;
 186 };
 187 /**
 188  * ABI function returning the __cxa_eh_globals structure.
 189  */
 190 __cxa_eh_globals *__cxa_get_globals(void);
 191 /**
 192  * Version of __cxa_get_globals() assuming that __cxa_get_globals() has already
 193  * been called at least once by this thread.
 194  */
 195 __cxa_eh_globals *__cxa_get_globals_fast(void);
 196
 197 std::type_info * __cxa_current_exception_type();
 198
 199 /**
 200  * Throws an exception returned by __cxa_current_primary_exception().  This
 201  * exception may have been caught in another thread.
 202  */
 203 void __cxa_rethrow_primary_exception(void* thrown_exception);
 204 /**
 205  * Returns the current exception in a form that can be stored in an
 206  * exception_ptr object and then rethrown by a call to
 207  * __cxa_rethrow_primary_exception().
 208  */
 209 void *__cxa_current_primary_exception(void);
 210 /**
 211  * Increments the reference count of an exception.  Called when an
 212  * exception_ptr is copied.
 213  */
 214 void __cxa_increment_exception_refcount(void* thrown_exception);
 215 /**
 216  * Decrements the reference count of an exception.  Called when an
 217  * exception_ptr is deleted.
 218  */
 219 void __cxa_decrement_exception_refcount(void* thrown_exception);
 220 /**
 221  * Demangles a C++ symbol or type name.  The buffer, if non-NULL, must be
 222  * allocated with malloc() and must be *n bytes or more long.  This function
 223  * may call realloc() on the value pointed to by buf, and will return the
 224  * length of the string via *n.
 225  *
 226  * The value pointed to by status is set to one of the following:
 227  *
 228  * 0: success
 229  * -1: memory allocation failure
 230  * -2: invalid mangled name
 231  * -3: invalid arguments
 232  */
 233 char* __cxa_demangle(const char* mangled_name,
 234                      char* buf,
 235                      size_t* n,
 236                      int* status);
 237 #ifdef __cplusplus
 238 } // extern "C"
 239 } // namespace
 240
 241 namespace abi = __cxxabiv1;
 242
 243 #endif /* __cplusplus */
 244 #endif /* __CXXABI_H_ */