contrib/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          * Now _Unwind_Exception is marked with __attribute__((aligned)), which
  82          * implies __cxa_exception is also aligned.  Insert padding in the
  83          * beginning of the struct, rather than before unwindHeader.
  84          */
  85         void *reserve;
  86
  87         /**
  88          * Reference count.  Used to support the C++11 exception_ptr class.  This
  89          * is prepended to the structure in 64-bit mode and squeezed in to the
  90          * padding left before the 64-bit aligned _Unwind_Exception at the end in
  91          * 32-bit mode.
  92          *
  93          * Note that it is safe to extend this structure at the beginning, rather
  94          * than the end, because the public API for creating it returns the address
  95          * of the end (where the exception object can be stored).
  96          */
  97         uintptr_t referenceCount;
  98 #endif
  99         /** Type info for the thrown object. */
 100         std::type_info *exceptionType;
 101         /** Destructor for the object, if one exists. */
 102         void (*exceptionDestructor) (void *);
 103         /** Handler called when an exception specification is violated. */
 104         unexpected_handler unexpectedHandler;
 105         /** Hander called to terminate. */
 106         terminate_handler terminateHandler;
 107         /**
 108          * Next exception in the list.  If an exception is thrown inside a catch
 109          * block and caught in a nested catch, this points to the exception that
 110          * will be handled after the inner catch block completes.
 111          */
 112         __cxa_exception *nextException;
 113         /**
 114          * The number of handlers that currently have references to this
 115          * exception.  The top (non-sign) bit of this is used as a flag to indicate
 116          * that the exception is being rethrown, so should not be deleted when its
 117          * handler count reaches 0 (which it doesn't with the top bit set).
 118          */
 119         int handlerCount;
 120 #if defined(__arm__) && !defined(__ARM_DWARF_EH__)
 121         /**
 122          * The ARM EH ABI requires the unwind library to keep track of exceptions
 123          * during cleanups.  These support nesting, so we need to keep a list of
 124          * them.
 125          */
 126         _Unwind_Exception *nextCleanup;
 127         /**
 128          * The number of cleanups that are currently being run on this exception.
 129          */
 130         int cleanupCount;
 131 #endif
 132         /**
 133          * The selector value to be returned when installing the catch handler.
 134          * Used at the call site to determine which catch() block should execute.
 135          * This is found in phase 1 of unwinding then installed in phase 2.
 136          */
 137         int handlerSwitchValue;
 138         /**
 139          * The action record for the catch.  This is cached during phase 1
 140          * unwinding.
 141          */
 142         const char *actionRecord;
 143         /**
 144          * Pointer to the language-specific data area (LSDA) for the handler
 145          * frame.  This is unused in this implementation, but set for ABI
 146          * compatibility in case we want to mix code in very weird ways.
 147          */
 148         const char *languageSpecificData;
 149         /** The cached landing pad for the catch handler.*/
 150         void *catchTemp;
 151         /**
 152          * The pointer that will be returned as the pointer to the object.  When
 153          * throwing a class and catching a virtual superclass (for example), we
 154          * need to adjust the thrown pointer to make it all work correctly.
 155          */
 156         void *adjustedPtr;
 157 #if !__LP64__
 158         /**
 159          * Reference count.  Used to support the C++11 exception_ptr class.  This
 160          * is prepended to the structure in 64-bit mode and squeezed in to the
 161          * padding left before the 64-bit aligned _Unwind_Exception at the end in
 162          * 32-bit mode.
 163          *
 164          * Note that it is safe to extend this structure at the beginning, rather
 165          * than the end, because the public API for creating it returns the address
 166          * of the end (where the exception object can be stored)
 167          */
 168         uintptr_t referenceCount;
 169 #endif
 170         /** The language-agnostic part of the exception header. */
 171         _Unwind_Exception unwindHeader;
 172 };
 173
 174 /**
 175  * ABI-specified globals structure.  Returned by the __cxa_get_globals()
 176  * function and its fast variant.  This is a per-thread structure - every
 177  * thread will have one lazily allocated.
 178  *
 179  * This structure is defined by the ABI, so may be used outside of this
 180  * library.
 181  */
 182 struct __cxa_eh_globals
 183 {
 184         /**
 185          * A linked list of exceptions that are currently caught.  There may be
 186          * several of these in nested catch() blocks.
 187          */
 188         __cxa_exception *caughtExceptions;
 189         /**
 190          * The number of uncaught exceptions.
 191          */
 192         unsigned int uncaughtExceptions;
 193 };
 194 /**
 195  * ABI function returning the __cxa_eh_globals structure.
 196  */
 197 __cxa_eh_globals *__cxa_get_globals(void);
 198 /**
 199  * Version of __cxa_get_globals() assuming that __cxa_get_globals() has already
 200  * been called at least once by this thread.
 201  */
 202 __cxa_eh_globals *__cxa_get_globals_fast(void);
 203
 204 std::type_info * __cxa_current_exception_type();
 205
 206
 207 void *__cxa_allocate_exception(size_t thrown_size) throw();
 208
 209 void __cxa_free_exception(void* thrown_exception) throw();
 210
 211 __cxa_exception *__cxa_init_primary_exception(
 212                 void *object, std::type_info* tinfo, void (*dest)(void *)) throw();
 213
 214 /**
 215  * Throws an exception returned by __cxa_current_primary_exception().  This
 216  * exception may have been caught in another thread.
 217  */
 218 void __cxa_rethrow_primary_exception(void* thrown_exception);
 219 /**
 220  * Returns the current exception in a form that can be stored in an
 221  * exception_ptr object and then rethrown by a call to
 222  * __cxa_rethrow_primary_exception().
 223  */
 224 void *__cxa_current_primary_exception(void);
 225 /**
 226  * Increments the reference count of an exception.  Called when an
 227  * exception_ptr is copied.
 228  */
 229 void __cxa_increment_exception_refcount(void* thrown_exception);
 230 /**
 231  * Decrements the reference count of an exception.  Called when an
 232  * exception_ptr is deleted.
 233  */
 234 void __cxa_decrement_exception_refcount(void* thrown_exception);
 235 /**
 236  * Demangles a C++ symbol or type name.  The buffer, if non-NULL, must be
 237  * allocated with malloc() and must be *n bytes or more long.  This function
 238  * may call realloc() on the value pointed to by buf, and will return the
 239  * length of the string via *n.
 240  *
 241  * The value pointed to by status is set to one of the following:
 242  *
 243  * 0: success
 244  * -1: memory allocation failure
 245  * -2: invalid mangled name
 246  * -3: invalid arguments
 247  */
 248 char* __cxa_demangle(const char* mangled_name,
 249                      char* buf,
 250                      size_t* n,
 251                      int* status);
 252 #ifdef __cplusplus
 253 } // extern "C"
 254 } // namespace
 255
 256 namespace abi = __cxxabiv1;
 257
 258 #endif /* __cplusplus */
 259 #endif /* __CXXABI_H_ */