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 any locals have changed. If any locals have changed we shouldn't OSR. 147 virtual bool HaveLocalsChanged() REQUIRES_SHARED(Locks::mutator_lock_) = 0; 148 }; 149 150 // Callback to let something request to be notified when reflective objects are being visited and 151 // updated to update any bare ArtMethod/ArtField pointers it might have. 152 class ReflectiveValueVisitCallback { 153 public: ~ReflectiveValueVisitCallback()154 virtual ~ReflectiveValueVisitCallback() {} 155 156 // Called when something visits all reflective values with the update visitor. 157 virtual void VisitReflectiveTargets(ReflectiveValueVisitor* visitor) 158 REQUIRES(Locks::mutator_lock_) = 0; 159 }; 160 161 class RuntimeCallbacks { 162 public: 163 RuntimeCallbacks(); 164 165 void AddThreadLifecycleCallback(ThreadLifecycleCallback* cb) REQUIRES(Locks::mutator_lock_); 166 void RemoveThreadLifecycleCallback(ThreadLifecycleCallback* cb) REQUIRES(Locks::mutator_lock_); 167 168 void ThreadStart(Thread* self) REQUIRES_SHARED(Locks::mutator_lock_); 169 void ThreadDeath(Thread* self) REQUIRES_SHARED(Locks::mutator_lock_); 170 171 void AddClassLoadCallback(ClassLoadCallback* cb) REQUIRES(Locks::mutator_lock_); 172 void RemoveClassLoadCallback(ClassLoadCallback* cb) REQUIRES(Locks::mutator_lock_); 173 174 void BeginDefineClass() REQUIRES_SHARED(Locks::mutator_lock_); 175 void EndDefineClass() REQUIRES_SHARED(Locks::mutator_lock_); 176 void ClassLoad(Handle<mirror::Class> klass) REQUIRES_SHARED(Locks::mutator_lock_); 177 void ClassPrepare(Handle<mirror::Class> temp_klass, Handle<mirror::Class> klass) 178 REQUIRES_SHARED(Locks::mutator_lock_); 179 180 void AddRuntimeSigQuitCallback(RuntimeSigQuitCallback* cb) 181 REQUIRES(Locks::mutator_lock_); 182 void RemoveRuntimeSigQuitCallback(RuntimeSigQuitCallback* cb) 183 REQUIRES(Locks::mutator_lock_); 184 185 void SigQuit() REQUIRES_SHARED(Locks::mutator_lock_); 186 187 void AddRuntimePhaseCallback(RuntimePhaseCallback* cb) 188 REQUIRES(Locks::mutator_lock_); 189 void RemoveRuntimePhaseCallback(RuntimePhaseCallback* cb) 190 REQUIRES(Locks::mutator_lock_); 191 192 void NextRuntimePhase(RuntimePhaseCallback::RuntimePhase phase) 193 REQUIRES_SHARED(Locks::mutator_lock_); 194 195 void ClassPreDefine(const char* descriptor, 196 Handle<mirror::Class> temp_class, 197 Handle<mirror::ClassLoader> loader, 198 const DexFile& initial_dex_file, 199 const dex::ClassDef& initial_class_def, 200 /*out*/DexFile const** final_dex_file, 201 /*out*/dex::ClassDef const** final_class_def) 202 REQUIRES_SHARED(Locks::mutator_lock_); 203 204 void AddMethodCallback(MethodCallback* cb) REQUIRES(Locks::mutator_lock_); 205 void RemoveMethodCallback(MethodCallback* cb) REQUIRES(Locks::mutator_lock_); 206 207 void RegisterNativeMethod(ArtMethod* method, 208 const void* original_implementation, 209 /*out*/void** new_implementation) 210 REQUIRES_SHARED(Locks::mutator_lock_); 211 212 void MonitorContendedLocking(Monitor* m) REQUIRES_SHARED(Locks::mutator_lock_); 213 void MonitorContendedLocked(Monitor* m) REQUIRES_SHARED(Locks::mutator_lock_); 214 void ObjectWaitStart(Handle<mirror::Object> m, int64_t timeout) 215 REQUIRES_SHARED(Locks::mutator_lock_); 216 void MonitorWaitFinished(Monitor* m, bool timed_out) 217 REQUIRES_SHARED(Locks::mutator_lock_); 218 219 void AddMonitorCallback(MonitorCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 220 void RemoveMonitorCallback(MonitorCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 221 222 void ThreadParkStart(bool is_absolute, int64_t timeout) REQUIRES_SHARED(Locks::mutator_lock_); 223 void ThreadParkFinished(bool timed_out) REQUIRES_SHARED(Locks::mutator_lock_); 224 void AddParkCallback(ParkCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 225 void RemoveParkCallback(ParkCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 226 227 // Returns true if any locals have changed. This is used to prevent OSRing frames that have 228 // some locals changed. 229 bool HaveLocalsChanged() REQUIRES_SHARED(Locks::mutator_lock_); 230 231 void AddMethodInspectionCallback(MethodInspectionCallback* cb) 232 REQUIRES_SHARED(Locks::mutator_lock_); 233 void RemoveMethodInspectionCallback(MethodInspectionCallback* cb) 234 REQUIRES_SHARED(Locks::mutator_lock_); 235 236 // DDMS callbacks 237 void DdmPublishChunk(uint32_t type, const ArrayRef<const uint8_t>& data) 238 REQUIRES_SHARED(Locks::mutator_lock_); 239 240 void AddDdmCallback(DdmCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 241 void RemoveDdmCallback(DdmCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_); 242 243 void StartDebugger() REQUIRES_SHARED(Locks::mutator_lock_); 244 // NO_THREAD_SAFETY_ANALYSIS since this is only called when we are in the middle of shutting down 245 // and the mutator_lock_ is no longer acquirable. 246 void StopDebugger() NO_THREAD_SAFETY_ANALYSIS; 247 bool IsDebuggerConfigured() REQUIRES_SHARED(Locks::mutator_lock_); 248 249 void AddDebuggerControlCallback(DebuggerControlCallback* cb) 250 REQUIRES_SHARED(Locks::mutator_lock_); 251 void RemoveDebuggerControlCallback(DebuggerControlCallback* cb) 252 REQUIRES_SHARED(Locks::mutator_lock_); 253 254 void VisitReflectiveTargets(ReflectiveValueVisitor* visitor) REQUIRES(Locks::mutator_lock_); 255 256 void AddReflectiveValueVisitCallback(ReflectiveValueVisitCallback* cb) 257 REQUIRES_SHARED(Locks::mutator_lock_); 258 void RemoveReflectiveValueVisitCallback(ReflectiveValueVisitCallback* cb) 259 REQUIRES_SHARED(Locks::mutator_lock_); 260 261 private: 262 std::unique_ptr<ReaderWriterMutex> callback_lock_ BOTTOM_MUTEX_ACQUIRED_AFTER; 263 264 std::vector<ThreadLifecycleCallback*> thread_callbacks_ 265 GUARDED_BY(callback_lock_); 266 std::vector<ClassLoadCallback*> class_callbacks_ 267 GUARDED_BY(callback_lock_); 268 std::vector<RuntimeSigQuitCallback*> sigquit_callbacks_ 269 GUARDED_BY(callback_lock_); 270 std::vector<RuntimePhaseCallback*> phase_callbacks_ 271 GUARDED_BY(callback_lock_); 272 std::vector<MethodCallback*> method_callbacks_ 273 GUARDED_BY(callback_lock_); 274 std::vector<MonitorCallback*> monitor_callbacks_ 275 GUARDED_BY(callback_lock_); 276 std::vector<ParkCallback*> park_callbacks_ 277 GUARDED_BY(callback_lock_); 278 std::vector<MethodInspectionCallback*> method_inspection_callbacks_ 279 GUARDED_BY(callback_lock_); 280 std::vector<DdmCallback*> ddm_callbacks_ 281 GUARDED_BY(callback_lock_); 282 std::vector<DebuggerControlCallback*> debugger_control_callbacks_ 283 GUARDED_BY(callback_lock_); 284 std::vector<ReflectiveValueVisitCallback*> reflective_value_visit_callbacks_ 285 GUARDED_BY(callback_lock_); 286 }; 287 288 } // namespace art 289 290 #endif // ART_RUNTIME_RUNTIME_CALLBACKS_H_ 291