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  * Exception handling.
  18  */
  19 #ifndef _DALVIK_EXCEPTION
  20 #define _DALVIK_EXCEPTION
  21
  22 /* initialization */
  23 bool dvmExceptionStartup(void);
  24 void dvmExceptionShutdown(void);
  25
  26 /*
  27  * Throw an exception in the current thread, by class descriptor.
  28  */
  29 void dvmThrowChainedException(const char* exceptionDescriptor, const char* msg,
  30     Object* cause);
  31 INLINE void dvmThrowException(const char* exceptionDescriptor,
  32     const char* msg)
  33 {
  34     dvmThrowChainedException(exceptionDescriptor, msg, NULL);
  35 }
  36
  37 /*
  38  * Throw an exception in the current thread, by class object.
  39  */
  40 void dvmThrowChainedExceptionByClass(ClassObject* exceptionClass,
  41     const char* msg, Object* cause);
  42 INLINE void dvmThrowExceptionByClass(ClassObject* exceptionClass,
  43     const char* msg)
  44 {
  45     dvmThrowChainedExceptionByClass(exceptionClass, msg, NULL);
  46 }
  47
  48 /*
  49  * Throw the named exception using the name of a class as the exception
  50  * message.
  51  */
  52 void dvmThrowChainedExceptionWithClassMessage(const char* exceptionDescriptor,
  53     const char* messageDescriptor, Object* cause);
  54 INLINE void dvmThrowExceptionWithClassMessage(const char* exceptionDescriptor,
  55     const char* messageDescriptor)
  56 {
  57     dvmThrowChainedExceptionWithClassMessage(exceptionDescriptor,
  58         messageDescriptor, NULL);
  59 }
  60
  61 /*
  62  * Like dvmThrowExceptionWithMessageFromDescriptor, but take a
  63  * class object instead of a name.
  64  */
  65 void dvmThrowExceptionByClassWithClassMessage(ClassObject* exceptionClass,
  66     const char* messageDescriptor);
  67
  68 /*
  69  * Return the exception being thrown in the current thread, or NULL if
  70  * no exception is pending.
  71  */
  72 INLINE Object* dvmGetException(Thread* self) {
  73     return self->exception;
  74 }
  75
  76 /*
  77  * Set the exception being thrown in the current thread.
  78  */
  79 INLINE void dvmSetException(Thread* self, Object* exception)
  80 {
  81     assert(exception != NULL);
  82     self->exception = exception;
  83 }
  84
  85 /*
  86  * Clear the pending exception.
  87  *
  88  * (We use this rather than "set(null)" because we may need to have special
  89  * fixups here for StackOverflowError stuff.  Calling "clear" in the code
  90  * makes it obvious.)
  91  */
  92 INLINE void dvmClearException(Thread* self) {
  93     self->exception = NULL;
  94 }
  95
  96 /*
  97  * Clear the pending exception.  Used by the optimization and verification
  98  * code, which has to run with "initializing" set to avoid going into a
  99  * death-spin if the "class not found" exception can't be found.
 100  */
 101 void dvmClearOptException(Thread* self);
 102
 103 /*
 104  * Returns "true" if an exception is pending.  Use this if you have a
 105  * "self" pointer.
 106  */
 107 INLINE bool dvmCheckException(Thread* self) {
 108     return (self->exception != NULL);
 109 }
 110
 111 /*
 112  * Returns "true" if this is a "checked" exception, i.e. it's a subclass
 113  * of Throwable (assumed) but not a subclass of RuntimeException or Error.
 114  */
 115 bool dvmIsCheckedException(const Object* exception);
 116
 117 /*
 118  * Wrap the now-pending exception in a different exception.
 119  *
 120  * If something fails, an (unchecked) exception related to that failure
 121  * will be pending instead.
 122  */
 123 void dvmWrapException(const char* newExcepStr);
 124
 125 /*
 126  * Get the "cause" field from an exception.
 127  *
 128  * Returns NULL if the field is null or uninitialized.
 129  */
 130 Object* dvmGetExceptionCause(const Object* exception);
 131
 132 /*
 133  * Print the exception stack trace on stderr.  Calls the exception's
 134  * print function.
 135  */
 136 void dvmPrintExceptionStackTrace(void);
 137
 138 /*
 139  * Print the exception stack trace to the log file.  The exception stack
 140  * trace is computed within the VM.
 141  */
 142 void dvmLogExceptionStackTrace(void);
 143
 144 /*
 145  * Search for a catch block that matches "exception".
 146  *
 147  * "*newFrame" gets a copy of the new frame pointer.
 148  *
 149  * If "doUnroll" is set, we unroll "thread"s stack as we go (and update
 150  * self->curFrame with the same value as in *newFrame).
 151  *
 152  * Returns the offset to the catch code on success, or -1 if we couldn't
 153  * find a catcher.
 154  */
 155 int dvmFindCatchBlock(Thread* self, int relPc, Object* exception,
 156     bool doUnroll, void** newFrame);
 157
 158 /*
 159  * Support for saving exception stack traces and converting them to
 160  * usable form.  Use the "FillIn" function to generate a compact array
 161  * that represents the stack frames, then "GetStackTrace" to convert it
 162  * to an array of StackTraceElement objects.
 163  *
 164  * Don't call the "Internal" form of the function directly.
 165  */
 166 void* dvmFillInStackTraceInternal(Thread* thread, bool wantObject, int* pCount);
 167 /* return an [I for use by interpreted code */
 168 INLINE Object* dvmFillInStackTrace(Thread* thread) {
 169     return (Object*) dvmFillInStackTraceInternal(thread, true, NULL);
 170 }
 171 ArrayObject* dvmGetStackTrace(const Object* stackState);
 172 /* return an int* and array count; caller must free() the return value */
 173 INLINE int* dvmFillInStackTraceRaw(Thread* thread, int* pCount) {
 174     return (int*) dvmFillInStackTraceInternal(thread, false, pCount);
 175 }
 176 ArrayObject* dvmGetStackTraceRaw(const int* intVals, int stackDepth);
 177
 178 /*
 179  * Print a formatted version of a raw stack trace to the log file.
 180  */
 181 void dvmLogRawStackTrace(const int* intVals, int stackDepth);
 182
 183 #endif /*_DALVIK_EXCEPTION*/