vm/Exception.h

   1 /*
   2  * Copyright (C) 2008 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /*
  18  * Exception handling.
  19  */
  20 #ifndef _DALVIK_EXCEPTION
  21 #define _DALVIK_EXCEPTION
  22
  23 /* initialization */
  24 bool dvmExceptionStartup(void);
  25 void dvmExceptionShutdown(void);
  26
  27 /*
  28  * Throw an exception in the current thread, by class descriptor.
  29  */
  30 void dvmThrowChainedException(const char* exceptionDescriptor, const char* msg,
  31     Object* cause);
  32 INLINE void dvmThrowException(const char* exceptionDescriptor,
  33     const char* msg)
  34 {
  35     dvmThrowChainedException(exceptionDescriptor, msg, NULL);
  36 }
  37
  38 /*
  39  * Throw an ArrayIndexOutOfBoundsException in the current thread, using the given
  40  * index and array length in the detail message.
  41  */
  42 void dvmThrowAIOOBE(int index, int length);
  43 /*
  44  * Throw an ArrayStoreException in the current thread, using the given classes'
  45  * names in the detail message.
  46  */
  47 void dvmThrowArrayStoreException(ClassObject* actual, ClassObject* desired);
  48
  49 /**
  50  * Throw a ClassCastException in the current thread, using the given classes'
  51  * names in the detail message.
  52  */
  53 void dvmThrowClassCastException(ClassObject* actual, ClassObject* desired);
  54
  55 /*
  56  * Like dvmThrowChainedException, but takes printf-style args for the message.
  57  */
  58 void dvmThrowExceptionFmtV(const char* exceptionDescriptor, const char* fmt,
  59     va_list args);
  60 void dvmThrowExceptionFmt(const char* exceptionDescriptor, const char* fmt, ...)
  61 #if defined(__GNUC__)
  62     __attribute__ ((format(printf, 2, 3)))
  63 #endif
  64     ;
  65 INLINE void dvmThrowExceptionFmt(const char* exceptionDescriptor,
  66     const char* fmt, ...)
  67 {
  68     va_list args;
  69     va_start(args, fmt);
  70     dvmThrowExceptionFmtV(exceptionDescriptor, fmt, args);
  71     va_end(args);
  72 }
  73
  74 /*
  75  * Throw an exception in the current thread, by class object.
  76  */
  77 void dvmThrowChainedExceptionByClass(ClassObject* exceptionClass,
  78     const char* msg, Object* cause);
  79 INLINE void dvmThrowExceptionByClass(ClassObject* exceptionClass,
  80     const char* msg)
  81 {
  82     dvmThrowChainedExceptionByClass(exceptionClass, msg, NULL);
  83 }
  84
  85 /*
  86  * Throw the named exception using the name of a class as the exception
  87  * message.
  88  */
  89 void dvmThrowChainedExceptionWithClassMessage(const char* exceptionDescriptor,
  90     const char* messageDescriptor, Object* cause);
  91 INLINE void dvmThrowExceptionWithClassMessage(const char* exceptionDescriptor,
  92     const char* messageDescriptor)
  93 {
  94     dvmThrowChainedExceptionWithClassMessage(exceptionDescriptor,
  95         messageDescriptor, NULL);
  96 }
  97
  98 /*
  99  * Like dvmThrowExceptionWithMessageFromDescriptor, but take a
 100  * class object instead of a name.
 101  */
 102 void dvmThrowExceptionByClassWithClassMessage(ClassObject* exceptionClass,
 103     const char* messageDescriptor);
 104
 105 /*
 106  * Return the exception being thrown in the current thread, or NULL if
 107  * no exception is pending.
 108  */
 109 INLINE Object* dvmGetException(Thread* self) {
 110     return self->exception;
 111 }
 112
 113 /*
 114  * Set the exception being thrown in the current thread.
 115  */
 116 INLINE void dvmSetException(Thread* self, Object* exception)
 117 {
 118     assert(exception != NULL);
 119     self->exception = exception;
 120 }
 121
 122 /*
 123  * Clear the pending exception.
 124  *
 125  * (We use this rather than "set(null)" because we may need to have special
 126  * fixups here for StackOverflowError stuff.  Calling "clear" in the code
 127  * makes it obvious.)
 128  */
 129 INLINE void dvmClearException(Thread* self) {
 130     self->exception = NULL;
 131 }
 132
 133 /*
 134  * Clear the pending exception.  Used by the optimization and verification
 135  * code, which has to run with "initializing" set to avoid going into a
 136  * death-spin if the "class not found" exception can't be found.
 137  */
 138 void dvmClearOptException(Thread* self);
 139
 140 /*
 141  * Returns "true" if an exception is pending.  Use this if you have a
 142  * "self" pointer.
 143  */
 144 INLINE bool dvmCheckException(Thread* self) {
 145     return (self->exception != NULL);
 146 }
 147
 148 /*
 149  * Returns "true" if this is a "checked" exception, i.e. it's a subclass
 150  * of Throwable (assumed) but not a subclass of RuntimeException or Error.
 151  */
 152 bool dvmIsCheckedException(const Object* exception);
 153
 154 /*
 155  * Wrap the now-pending exception in a different exception.
 156  *
 157  * If something fails, an (unchecked) exception related to that failure
 158  * will be pending instead.
 159  */
 160 void dvmWrapException(const char* newExcepStr);
 161
 162 /*
 163  * Get the "cause" field from an exception.
 164  *
 165  * Returns NULL if the field is null or uninitialized.
 166  */
 167 Object* dvmGetExceptionCause(const Object* exception);
 168
 169 /*
 170  * Print the exception stack trace on stderr.  Calls the exception's
 171  * print function.
 172  */
 173 void dvmPrintExceptionStackTrace(void);
 174
 175 /*
 176  * Print the exception stack trace to the log file.  The exception stack
 177  * trace is computed within the VM.
 178  */
 179 void dvmLogExceptionStackTrace(void);
 180
 181 /*
 182  * Search for a catch block that matches "exception".
 183  *
 184  * "*newFrame" gets a copy of the new frame pointer.
 185  *
 186  * If "doUnroll" is set, we unroll "thread"s stack as we go (and update
 187  * self->curFrame with the same value as in *newFrame).
 188  *
 189  * Returns the offset to the catch code on success, or -1 if we couldn't
 190  * find a catcher.
 191  */
 192 int dvmFindCatchBlock(Thread* self, int relPc, Object* exception,
 193     bool doUnroll, void** newFrame);
 194
 195 /*
 196  * Support for saving exception stack traces and converting them to
 197  * usable form.  Use the "FillIn" function to generate a compact array
 198  * that represents the stack frames, then "GetStackTrace" to convert it
 199  * to an array of StackTraceElement objects.
 200  *
 201  * Don't call the "Internal" form of the function directly.
 202  */
 203 void* dvmFillInStackTraceInternal(Thread* thread, bool wantObject, int* pCount);
 204 /* return an [I for use by interpreted code */
 205 INLINE Object* dvmFillInStackTrace(Thread* thread) {
 206     return (Object*) dvmFillInStackTraceInternal(thread, true, NULL);
 207 }
 208 ArrayObject* dvmGetStackTrace(const Object* stackState);
 209 /* return an int* and array count; caller must free() the return value */
 210 INLINE int* dvmFillInStackTraceRaw(Thread* thread, int* pCount) {
 211     return (int*) dvmFillInStackTraceInternal(thread, false, pCount);
 212 }
 213 ArrayObject* dvmGetStackTraceRaw(const int* intVals, int stackDepth);
 214
 215 /*
 216  * Print a formatted version of a raw stack trace to the log file.
 217  */
 218 void dvmLogRawStackTrace(const int* intVals, int stackDepth);
 219
 220 #endif /*_DALVIK_EXCEPTION*/