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