1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_ANDROID_JNI_ANDROID_H_ 6 #define BASE_ANDROID_JNI_ANDROID_H_ 7 8 #include <jni.h> 9 #include <sys/types.h> 10 11 #include <string> 12 13 #include "base/android/scoped_java_ref.h" 14 #include "base/atomicops.h" 15 #include "base/base_export.h" 16 #include "base/compiler_specific.h" 17 #include "base/debug/stack_trace.h" 18 #include "base/macros.h" 19 20 #if HAVE_TRACE_STACK_FRAME_POINTERS 21 22 // When profiling is enabled (enable_profiling=true) this macro is added to 23 // all generated JNI stubs so that it becomes the last thing that runs before 24 // control goes into Java. 25 // 26 // This macro saves stack frame pointer of the current function. Saved value 27 // used later by JNI_LINK_SAVED_FRAME_POINTER. 28 #define JNI_SAVE_FRAME_POINTER \ 29 base::android::JNIStackFrameSaver jni_frame_saver(__builtin_frame_address(0)) 30 31 // When profiling is enabled (enable_profiling=true) this macro is added to 32 // all generated JNI callbacks so that it becomes the first thing that runs 33 // after control returns from Java. 34 // 35 // This macro links stack frame of the current function to the stack frame 36 // saved by JNI_SAVE_FRAME_POINTER, allowing frame-based unwinding 37 // (used by the heap profiler) to produce complete traces. 38 #define JNI_LINK_SAVED_FRAME_POINTER \ 39 base::debug::ScopedStackFrameLinker jni_frame_linker( \ 40 __builtin_frame_address(0), \ 41 base::android::JNIStackFrameSaver::SavedFrame()) 42 43 #else 44 45 // Frame-based stack unwinding is not supported, do nothing. 46 #define JNI_SAVE_FRAME_POINTER 47 #define JNI_LINK_SAVED_FRAME_POINTER 48 49 #endif // HAVE_TRACE_STACK_FRAME_POINTERS 50 51 namespace base { 52 namespace android { 53 54 // Used to mark symbols to be exported in a shared library's symbol table. 55 #define JNI_EXPORT __attribute__ ((visibility("default"))) 56 57 // The level of JNI registration required for the current process. 58 enum JniRegistrationType { 59 // Register all native methods. 60 ALL_JNI_REGISTRATION, 61 // Register some native methods, as controlled by the jni_generator. 62 SELECTIVE_JNI_REGISTRATION, 63 // Do not register any native methods. 64 NO_JNI_REGISTRATION, 65 }; 66 67 BASE_EXPORT JniRegistrationType GetJniRegistrationType(); 68 69 // Set the JniRegistrationType for this process (defaults to 70 // ALL_JNI_REGISTRATION). This should be called in the JNI_OnLoad function 71 // which is called when the native library is first loaded. 72 BASE_EXPORT void SetJniRegistrationType( 73 JniRegistrationType jni_registration_type); 74 75 // Contains the registration method information for initializing JNI bindings. 76 struct RegistrationMethod { 77 const char* name; 78 bool (*func)(JNIEnv* env); 79 }; 80 81 // Attaches the current thread to the VM (if necessary) and return the JNIEnv*. 82 BASE_EXPORT JNIEnv* AttachCurrentThread(); 83 84 // Same to AttachCurrentThread except that thread name will be set to 85 // |thread_name| if it is the first call. Otherwise, thread_name won't be 86 // changed. AttachCurrentThread() doesn't regard underlying platform thread 87 // name, but just resets it to "Thread-???". This function should be called 88 // right after new thread is created if it is important to keep thread name. 89 BASE_EXPORT JNIEnv* AttachCurrentThreadWithName(const std::string& thread_name); 90 91 // Detaches the current thread from VM if it is attached. 92 BASE_EXPORT void DetachFromVM(); 93 94 // Initializes the global JVM. 95 BASE_EXPORT void InitVM(JavaVM* vm); 96 97 // Returns true if the global JVM has been initialized. 98 BASE_EXPORT bool IsVMInitialized(); 99 100 // Initializes the global ClassLoader used by the GetClass and LazyGetClass 101 // methods. This is needed because JNI will use the base ClassLoader when there 102 // is no Java code on the stack. The base ClassLoader doesn't know about any of 103 // the application classes and will fail to lookup anything other than system 104 // classes. 105 BASE_EXPORT void InitReplacementClassLoader( 106 JNIEnv* env, 107 const JavaRef<jobject>& class_loader); 108 109 // Finds the class named |class_name| and returns it. 110 // Use this method instead of invoking directly the JNI FindClass method (to 111 // prevent leaking local references). 112 // This method triggers a fatal assertion if the class could not be found. 113 // Use HasClass if you need to check whether the class exists. 114 BASE_EXPORT ScopedJavaLocalRef<jclass> GetClass(JNIEnv* env, 115 const char* class_name); 116 117 // The method will initialize |atomic_class_id| to contain a global ref to the 118 // class. And will return that ref on subsequent calls. It's the caller's 119 // responsibility to release the ref when it is no longer needed. 120 // The caller is responsible to zero-initialize |atomic_method_id|. 121 // It's fine to simultaneously call this on multiple threads referencing the 122 // same |atomic_method_id|. 123 BASE_EXPORT jclass LazyGetClass( 124 JNIEnv* env, 125 const char* class_name, 126 base::subtle::AtomicWord* atomic_class_id); 127 128 // This class is a wrapper for JNIEnv Get(Static)MethodID. 129 class BASE_EXPORT MethodID { 130 public: 131 enum Type { 132 TYPE_STATIC, 133 TYPE_INSTANCE, 134 }; 135 136 // Returns the method ID for the method with the specified name and signature. 137 // This method triggers a fatal assertion if the method could not be found. 138 template<Type type> 139 static jmethodID Get(JNIEnv* env, 140 jclass clazz, 141 const char* method_name, 142 const char* jni_signature); 143 144 // The caller is responsible to zero-initialize |atomic_method_id|. 145 // It's fine to simultaneously call this on multiple threads referencing the 146 // same |atomic_method_id|. 147 template<Type type> 148 static jmethodID LazyGet(JNIEnv* env, 149 jclass clazz, 150 const char* method_name, 151 const char* jni_signature, 152 base::subtle::AtomicWord* atomic_method_id); 153 }; 154 155 // Returns true if an exception is pending in the provided JNIEnv*. 156 BASE_EXPORT bool HasException(JNIEnv* env); 157 158 // If an exception is pending in the provided JNIEnv*, this function clears it 159 // and returns true. 160 BASE_EXPORT bool ClearException(JNIEnv* env); 161 162 // This function will call CHECK() macro if there's any pending exception. 163 BASE_EXPORT void CheckException(JNIEnv* env); 164 165 // This returns a string representation of the java stack trace. 166 BASE_EXPORT std::string GetJavaExceptionInfo(JNIEnv* env, 167 jthrowable java_throwable); 168 169 #if HAVE_TRACE_STACK_FRAME_POINTERS 170 171 // Saves caller's PC and stack frame in a thread-local variable. 172 // Implemented only when profiling is enabled (enable_profiling=true). 173 class BASE_EXPORT JNIStackFrameSaver { 174 public: 175 JNIStackFrameSaver(void* current_fp); 176 ~JNIStackFrameSaver(); 177 static void* SavedFrame(); 178 179 private: 180 void* previous_fp_; 181 182 DISALLOW_COPY_AND_ASSIGN(JNIStackFrameSaver); 183 }; 184 185 #endif // HAVE_TRACE_STACK_FRAME_POINTERS 186 187 } // namespace android 188 } // namespace base 189 190 #endif // BASE_ANDROID_JNI_ANDROID_H_ 191