1 /* 2 * Copyright (C) 2017 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 #ifndef ART_RUNTIME_RUNTIME_CALLBACKS_H_ 18 #define ART_RUNTIME_RUNTIME_CALLBACKS_H_ 19 20 #include <vector> 21 22 #include "base/array_ref.h" 23 #include "base/locks.h" 24 #include "base/macros.h" 25 #include "handle.h" 26 27 namespace art { 28 29 namespace dex { 30 struct ClassDef; 31 } // namespace dex 32 33 namespace mirror { 34 class Class; 35 class ClassLoader; 36 class Object; 37 } // namespace mirror 38 39 class ArtMethod; 40 class ClassLoadCallback; 41 class DexFile; 42 class Thread; 43 class MethodCallback; 44 class Monitor; 45 class ReaderWriterMutex; 46 class ThreadLifecycleCallback; 47 class ReflectiveValueVisitor; 48 49 // Note: RuntimeCallbacks uses the mutator lock to synchronize the callback lists. A thread must 50 // hold the exclusive lock to add or remove a listener. A thread must hold the shared lock 51 // to dispatch an event. This setup is chosen as some clients may want to suspend the 52 // dispatching thread or all threads. 53 // 54 // To make this safe, the following restrictions apply: 55 // * Only the owner of a listener may ever add or remove said listener. 56 // * A listener must never add or remove itself or any other listener while running. 57 // * It is the responsibility of the owner to not remove the listener while it is running 58 // (and suspended). 59 // * The owner should never deallocate a listener once it has been registered, even if it has 60 // been removed. 61 // 62 // The simplest way to satisfy these restrictions is to never remove a listener, and to do 63 // any state checking (is the listener enabled) in the listener itself. For an example, see 64 // Dbg. 65 66 class DdmCallback { 67 public: ~DdmCallback()68 virtual ~DdmCallback() {} 69 virtual void DdmPublishChunk(uint32_t type, const ArrayRef<const uint8_t>& data) 70 REQUIRES_SHARED(Locks::mutator_lock_) = 0; 71 }; 72 73 class DebuggerControlCallback { 74 public: ~DebuggerControlCallback()75 virtual ~DebuggerControlCallback() {} 76 77 // Begin running the debugger. 78 virtual void StartDebugger() = 0; 79 // The debugger should begin shutting down since the runtime is ending. This is just advisory 80 virtual void StopDebugger() = 0; 81 82 // This allows the debugger to tell the runtime if it is configured. 83 virtual bool IsDebuggerConfigured() = 0; 84 }; 85 86 class RuntimeSigQuitCallback { 87 public: ~RuntimeSigQuitCallback()88 virtual ~RuntimeSigQuitCallback() {} 89 90 virtual void SigQuit() REQUIRES_SHARED(Locks::mutator_lock_) = 0; 91 }; 92 93 class RuntimePhaseCallback { 94 public: 95 enum RuntimePhase { 96 kInitialAgents, // Initial agent loading is done. 97 kStart, // The runtime is started. 98 kInit, // The runtime is initialized (and will run user code soon). 99 kDeath, // The runtime just died. 100 }; 101 ~RuntimePhaseCallback()102 virtual ~RuntimePhaseCallback() {} 103 104 virtual void NextRuntimePhase(RuntimePhase phase) REQUIRES_SHARED(Locks::mutator_lock_) = 0; 105 }; 106 107 class MonitorCallback { 108 public: 109 // Called just before the thread goes to sleep to wait for the monitor to become unlocked. 110 virtual void MonitorContendedLocking(Monitor* mon) REQUIRES_SHARED(Locks::mutator_lock_) = 0; 111 // Called just after the monitor has been successfully acquired when it was already locked. 112 virtual void MonitorContendedLocked(Monitor* mon) REQUIRES_SHARED(Locks::mutator_lock_) = 0; 113 // Called on entry to the Object#wait method regardless of whether or not the call is valid. 114 virtual void ObjectWaitStart(Handle<mirror::Object> obj, int64_t millis_timeout) 115 REQUIRES_SHARED(Locks::mutator_lock_) = 0; 116 117 // Called just after the monitor has woken up from going to sleep for a wait(). At this point the 118 // thread does not possess a lock on the monitor. This will only be called for threads wait calls 119 // where the thread did (or at least could have) gone to sleep. 120 virtual void MonitorWaitFinished(Monitor* m, bool timed_out) 121 REQUIRES_SHARED(Locks::mutator_lock_) = 0; 122 ~MonitorCallback()123 virtual ~MonitorCallback() {} 124 }; 125 126 class ParkCallback { 127 public: 128 // Called on entry to the Unsafe.#park method 129 virtual void ThreadParkStart(bool is_absolute, int64_t millis_timeout) 130 REQUIRES_SHARED(Locks::mutator_lock_) = 0; 131 132 // Called just after the thread has woken up from going to sleep for a park(). This will only be 133 // called for Unsafe.park() calls where the thread did (or at least could have) gone to sleep. 134 virtual void ThreadParkFinished(bool timed_out) REQUIRES_SHARED(Locks::mutator_lock_) = 0; 135 ~ParkCallback()136 virtual ~ParkCallback() {} 137 }; 138 139 // A callback to let parts of the runtime note that they are currently relying on a particular 140 // method remaining in it's current state. Users should not rely on always being called. If multiple 141 // callbacks are added the runtime will short-circuit when the first one returns 'true'. 142 class MethodInspectionCallback { 143 public: ~MethodInspectionCallback()144 virtual ~MethodInspectionCallback() {} 145 146 // Returns true if the method is being inspected currently and the runtime should not modify it in 147 // potentially dangerous ways (i.e. replace with compiled version, JIT it, etc). 148 virtual bool IsMethodBeingInspected(ArtMethod* method) REQUIRES_SHARED(Locks::mutator_lock_) = 0; 149 150 // Returns true if the method is safe to Jit, false otherwise. 151 // Note that '!IsMethodSafeToJit(m) implies IsMethodBeingInspected(m)'. That is that if this 152 // method returns false IsMethodBeingInspected must return true. 153 virtual bool IsMethodSafeToJit(ArtMethod* method) REQUIRES_SHARED(Locks::mutator_lock_) = 0; 154 155 // Returns true if we expect the method to be debuggable but are not doing anything unusual with 156 // it currently. 157 virtual bool MethodNeedsDebugVersion(ArtMethod* method) REQUIRES_SHARED(Locks::mutator_lock_) = 0; 158 }; 159 160 // Callback to let something request to be notified when reflective objects are being visited and 161 // updated to update any bare ArtMethod/ArtField pointers it might have. 162 class ReflectiveValueVisitCallback { 163 public: ~ReflectiveValueVisitCallback()164 virtual ~ReflectiveValueVisitCallback() {} 165 166 // Called when something visits all reflective values with the update visitor. 167 virtual void VisitReflectiveTargets(ReflectiveValueVisitor* visitor) 168 REQUIRES(Locks::mutator_lock_) = 0; 169 }; 170 171 class RuntimeCallbacks { 172 public: 173 RuntimeCallbacks(); 174 175 void AddThreadLifecycleCallback(ThreadLifecycleCallback* cb) REQUIRES(Locks::mutator_lock_); 176 void RemoveThreadLifecycleCallback(ThreadLifecycleCallback* cb) REQUIRES(Locks::mutator_lock_); 177 178 void ThreadStart(Thread* self) REQUIRES_SHARED(Locks::mutator_lock_); 179 void ThreadDeath(Thread* self) REQUIRES_SHARED(Locks::mutator_lock_); 180 181 void AddClassLoadCallback(ClassLoadCallback* cb) REQUIRES(Locks::mutator_lock_); 182 void RemoveClassLoadCallback(ClassLoadCallback* cb) REQUIRES(Locks::mutator_lock_); 183 184 void BeginDefineClass() REQUIRES_SHARED(Locks::mutator_lock_); 185 void EndDefineClass() REQUIRES_SHARED(Locks::mutator_lock_); 186 void ClassLoad(Handle<mirror::Class> klass) REQUIRES_SHARED(Locks::mutator_lock_); 187 void ClassPrepare(Handle<mirror::Class> temp_klass, Handle<mirror::Class> klass) 188 REQUIRES_SHARED(Locks::mutator_lock_); 189 190 void AddRuntimeSigQuitCallback(RuntimeSigQuitCallback* cb) 191 REQUIRES(Locks::mutator_lock_); 192 void RemoveRuntimeSigQuitCallback(RuntimeSigQuitCallback* cb) 193 REQUIRES(Locks::mutator_lock_); 194 195 void SigQuit() REQUIRES_SHARED(Locks::mutator_lock_); 196 197 void AddRuntimePhaseCallback(RuntimePhaseCallback* cb) 198 REQUIRES(Locks::mutator_lock_); 199 void RemoveRuntimePhaseCallback(RuntimePhaseCallback* cb) 200 REQUIRES(Locks::mutator_lock_); 201 202 void NextRuntimePhase(RuntimePhaseCallback::RuntimePhase phase) 203 REQUIRES_SHARED(Locks::mutator_lock_); 204 205 void ClassPreDefine(const char* descriptor, 206 Handle<mirror::Class> temp_class, 207 Handle<mirror::ClassLoader> loader, 208 const DexFile& initial_dex_file, 209 const dex::ClassDef& initial_class_def, 210 /*out*/DexFile const** final_dex_file, 211 /*out*/dex::ClassDef const** final_class_def) 212 REQUIRES_SHARED(Locks::mutator_lock_); 213 214 void AddMethodCallback(MethodCallback* cb) REQUIRES(Locks::mutator_lock_); 215 void RemoveMethodCallback(MethodCallback* cb) REQUIRES(Locks::mutator_lock_); 216 217 void RegisterNativeMethod(ArtMethod* method, 218 const void* original_implementation, 219 /*out*/void** new_implementation) 220 REQUIRES_SHARED(Locks::mutator_lock_); 221 222 void MonitorContendedLocking(Monitor* m) REQUIRES_SHARED(Locks::mutator_lock_); 223 void MonitorContendedLocked(Monitor* m) REQUIRES_SHARED(Locks::mutator_lock_); 224 void ObjectWaitStart(Handle<mirror::Object> m, int64_t timeout) 225 REQUIRES_SHARED(Locks::mutator_lock_); 226 void MonitorWaitFinished(Monitor* m, bool timed_out) 227 REQUIRES_SHARED(Locks::mutator_lock_); 228 229 void AddMonitorCallback(MonitorCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 230 void RemoveMonitorCallback(MonitorCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 231 232 void ThreadParkStart(bool is_absolute, int64_t timeout) REQUIRES_SHARED(Locks::mutator_lock_); 233 void ThreadParkFinished(bool timed_out) REQUIRES_SHARED(Locks::mutator_lock_); 234 void AddParkCallback(ParkCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 235 void RemoveParkCallback(ParkCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 236 237 // Returns true if some MethodInspectionCallback indicates the method is being inspected/depended 238 // on by some code. 239 bool IsMethodBeingInspected(ArtMethod* method) REQUIRES_SHARED(Locks::mutator_lock_); 240 241 // Returns false if some MethodInspectionCallback indicates the method cannot be safetly jitted 242 // (which implies that it is being Inspected). Returns true otherwise. If it returns false the 243 // entrypoint should not be changed to JITed code. 244 bool IsMethodSafeToJit(ArtMethod* method) REQUIRES_SHARED(Locks::mutator_lock_); 245 246 // Returns true if some MethodInspectionCallback indicates the method needs to use a debug 247 // version. This allows later code to set breakpoints or perform other actions that could be 248 // broken by some optimizations. 249 bool MethodNeedsDebugVersion(ArtMethod* method) REQUIRES_SHARED(Locks::mutator_lock_); 250 251 void AddMethodInspectionCallback(MethodInspectionCallback* cb) 252 REQUIRES_SHARED(Locks::mutator_lock_); 253 void RemoveMethodInspectionCallback(MethodInspectionCallback* cb) 254 REQUIRES_SHARED(Locks::mutator_lock_); 255 256 // DDMS callbacks 257 void DdmPublishChunk(uint32_t type, const ArrayRef<const uint8_t>& data) 258 REQUIRES_SHARED(Locks::mutator_lock_); 259 260 void AddDdmCallback(DdmCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 261 void RemoveDdmCallback(DdmCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 262 263 void StartDebugger() REQUIRES_SHARED(Locks::mutator_lock_); 264 // NO_THREAD_SAFETY_ANALYSIS since this is only called when we are in the middle of shutting down 265 // and the mutator_lock_ is no longer acquirable. 266 void StopDebugger() NO_THREAD_SAFETY_ANALYSIS; 267 bool IsDebuggerConfigured() REQUIRES_SHARED(Locks::mutator_lock_); 268 269 void AddDebuggerControlCallback(DebuggerControlCallback* cb) 270 REQUIRES_SHARED(Locks::mutator_lock_); 271 void RemoveDebuggerControlCallback(DebuggerControlCallback* cb) 272 REQUIRES_SHARED(Locks::mutator_lock_); 273 274 void VisitReflectiveTargets(ReflectiveValueVisitor* visitor) REQUIRES(Locks::mutator_lock_); 275 276 void AddReflectiveValueVisitCallback(ReflectiveValueVisitCallback* cb) 277 REQUIRES_SHARED(Locks::mutator_lock_); 278 void RemoveReflectiveValueVisitCallback(ReflectiveValueVisitCallback* cb) 279 REQUIRES_SHARED(Locks::mutator_lock_); 280 281 private: 282 std::unique_ptr<ReaderWriterMutex> callback_lock_ BOTTOM_MUTEX_ACQUIRED_AFTER; 283 284 std::vector<ThreadLifecycleCallback*> thread_callbacks_ 285 GUARDED_BY(callback_lock_); 286 std::vector<ClassLoadCallback*> class_callbacks_ 287 GUARDED_BY(callback_lock_); 288 std::vector<RuntimeSigQuitCallback*> sigquit_callbacks_ 289 GUARDED_BY(callback_lock_); 290 std::vector<RuntimePhaseCallback*> phase_callbacks_ 291 GUARDED_BY(callback_lock_); 292 std::vector<MethodCallback*> method_callbacks_ 293 GUARDED_BY(callback_lock_); 294 std::vector<MonitorCallback*> monitor_callbacks_ 295 GUARDED_BY(callback_lock_); 296 std::vector<ParkCallback*> park_callbacks_ 297 GUARDED_BY(callback_lock_); 298 std::vector<MethodInspectionCallback*> method_inspection_callbacks_ 299 GUARDED_BY(callback_lock_); 300 std::vector<DdmCallback*> ddm_callbacks_ 301 GUARDED_BY(callback_lock_); 302 std::vector<DebuggerControlCallback*> debugger_control_callbacks_ 303 GUARDED_BY(callback_lock_); 304 std::vector<ReflectiveValueVisitCallback*> reflective_value_visit_callbacks_ 305 GUARDED_BY(callback_lock_); 306 }; 307 308 } // namespace art 309 310 #endif // ART_RUNTIME_RUNTIME_CALLBACKS_H_ 311