• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 HIDDEN {
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 AppInfoCallback {
74  public:
~AppInfoCallback()75   virtual ~AppInfoCallback() {}
76   virtual void SetCurrentProcessName(const std::string& process_name)
77       REQUIRES_SHARED(Locks::mutator_lock_) = 0;
78   virtual void AddApplication(const std::string& package_name)
79       REQUIRES_SHARED(Locks::mutator_lock_) = 0;
80   virtual void RemoveApplication(const std::string& package_name)
81       REQUIRES_SHARED(Locks::mutator_lock_) = 0;
82   virtual void SetWaitingForDebugger(bool waiting) REQUIRES_SHARED(Locks::mutator_lock_) = 0;
83   virtual void SetUserId(int uid) REQUIRES_SHARED(Locks::mutator_lock_) = 0;
84 };
85 
86 class DebuggerControlCallback {
87  public:
~DebuggerControlCallback()88   virtual ~DebuggerControlCallback() {}
89 
90   // Begin running the debugger.
91   virtual void StartDebugger() = 0;
92   // The debugger should begin shutting down since the runtime is ending. This is just advisory
93   virtual void StopDebugger() = 0;
94 
95   // This allows the debugger to tell the runtime if it is configured.
96   virtual bool IsDebuggerConfigured() = 0;
97 };
98 
99 class RuntimeSigQuitCallback {
100  public:
~RuntimeSigQuitCallback()101   virtual ~RuntimeSigQuitCallback() {}
102 
103   virtual void SigQuit() REQUIRES_SHARED(Locks::mutator_lock_) = 0;
104 };
105 
106 class RuntimePhaseCallback {
107  public:
108   enum RuntimePhase {
109     kInitialAgents,   // Initial agent loading is done.
110     kStart,           // The runtime is started.
111     kInit,            // The runtime is initialized (and will run user code soon).
112     kDeath,           // The runtime just died.
113   };
114 
~RuntimePhaseCallback()115   virtual ~RuntimePhaseCallback() {}
116 
117   virtual void NextRuntimePhase(RuntimePhase phase) REQUIRES_SHARED(Locks::mutator_lock_) = 0;
118 };
119 
120 class MonitorCallback {
121  public:
122   // Called just before the thread goes to sleep to wait for the monitor to become unlocked.
123   virtual void MonitorContendedLocking(Monitor* mon) REQUIRES_SHARED(Locks::mutator_lock_) = 0;
124   // Called just after the monitor has been successfully acquired when it was already locked.
125   virtual void MonitorContendedLocked(Monitor* mon) REQUIRES_SHARED(Locks::mutator_lock_) = 0;
126   // Called on entry to the Object#wait method regardless of whether or not the call is valid.
127   virtual void ObjectWaitStart(Handle<mirror::Object> obj, int64_t millis_timeout)
128       REQUIRES_SHARED(Locks::mutator_lock_) = 0;
129 
130   // Called just after the monitor has woken up from going to sleep for a wait(). At this point the
131   // thread does not possess a lock on the monitor. This will only be called for threads wait calls
132   // where the thread did (or at least could have) gone to sleep.
133   virtual void MonitorWaitFinished(Monitor* m, bool timed_out)
134       REQUIRES_SHARED(Locks::mutator_lock_) = 0;
135 
~MonitorCallback()136   virtual ~MonitorCallback() {}
137 };
138 
139 class ParkCallback {
140  public:
141   // Called on entry to the Unsafe.#park method
142   virtual void ThreadParkStart(bool is_absolute, int64_t millis_timeout)
143       REQUIRES_SHARED(Locks::mutator_lock_) = 0;
144 
145   // Called just after the thread has woken up from going to sleep for a park(). This will only be
146   // called for Unsafe.park() calls where the thread did (or at least could have) gone to sleep.
147   virtual void ThreadParkFinished(bool timed_out) REQUIRES_SHARED(Locks::mutator_lock_) = 0;
148 
~ParkCallback()149   virtual ~ParkCallback() {}
150 };
151 
152 // A callback to let parts of the runtime note that they are currently relying on a particular
153 // method remaining in it's current state. Users should not rely on always being called. If multiple
154 // callbacks are added the runtime will short-circuit when the first one returns 'true'.
155 class MethodInspectionCallback {
156  public:
~MethodInspectionCallback()157   virtual ~MethodInspectionCallback() {}
158 
159   // Returns true if any locals have changed. If any locals have changed we shouldn't OSR.
160   virtual bool HaveLocalsChanged() REQUIRES_SHARED(Locks::mutator_lock_) = 0;
161 };
162 
163 // Callback to let something request to be notified when reflective objects are being visited and
164 // updated to update any bare ArtMethod/ArtField pointers it might have.
165 class ReflectiveValueVisitCallback {
166  public:
~ReflectiveValueVisitCallback()167   virtual ~ReflectiveValueVisitCallback() {}
168 
169   // Called when something visits all reflective values with the update visitor.
170   virtual void VisitReflectiveTargets(ReflectiveValueVisitor* visitor)
171       REQUIRES(Locks::mutator_lock_) = 0;
172 };
173 
174 class EXPORT RuntimeCallbacks {
175  public:
176   RuntimeCallbacks();
177 
178   void AddThreadLifecycleCallback(ThreadLifecycleCallback* cb) REQUIRES(Locks::mutator_lock_);
179   void RemoveThreadLifecycleCallback(ThreadLifecycleCallback* cb) REQUIRES(Locks::mutator_lock_);
180 
181   void ThreadStart(Thread* self) REQUIRES_SHARED(Locks::mutator_lock_);
182   void ThreadDeath(Thread* self) REQUIRES_SHARED(Locks::mutator_lock_);
183 
184   void AddClassLoadCallback(ClassLoadCallback* cb) REQUIRES(Locks::mutator_lock_);
185   void RemoveClassLoadCallback(ClassLoadCallback* cb) REQUIRES(Locks::mutator_lock_);
186 
187   void BeginDefineClass() REQUIRES_SHARED(Locks::mutator_lock_);
188   void EndDefineClass() REQUIRES_SHARED(Locks::mutator_lock_);
189   void ClassLoad(Handle<mirror::Class> klass) REQUIRES_SHARED(Locks::mutator_lock_);
190   void ClassPrepare(Handle<mirror::Class> temp_klass, Handle<mirror::Class> klass)
191       REQUIRES_SHARED(Locks::mutator_lock_);
192 
193   void AddRuntimeSigQuitCallback(RuntimeSigQuitCallback* cb)
194       REQUIRES(Locks::mutator_lock_);
195   void RemoveRuntimeSigQuitCallback(RuntimeSigQuitCallback* cb)
196       REQUIRES(Locks::mutator_lock_);
197 
198   void SigQuit() REQUIRES_SHARED(Locks::mutator_lock_);
199 
200   void AddRuntimePhaseCallback(RuntimePhaseCallback* cb)
201       REQUIRES(Locks::mutator_lock_);
202   void RemoveRuntimePhaseCallback(RuntimePhaseCallback* cb)
203       REQUIRES(Locks::mutator_lock_);
204 
205   void NextRuntimePhase(RuntimePhaseCallback::RuntimePhase phase)
206       REQUIRES_SHARED(Locks::mutator_lock_);
207 
208   void ClassPreDefine(const char* descriptor,
209                       Handle<mirror::Class> temp_class,
210                       Handle<mirror::ClassLoader> loader,
211                       const DexFile& initial_dex_file,
212                       const dex::ClassDef& initial_class_def,
213                       /*out*/DexFile const** final_dex_file,
214                       /*out*/dex::ClassDef const** final_class_def)
215       REQUIRES_SHARED(Locks::mutator_lock_);
216 
217   void AddMethodCallback(MethodCallback* cb) REQUIRES(Locks::mutator_lock_);
218   void RemoveMethodCallback(MethodCallback* cb) REQUIRES(Locks::mutator_lock_);
219 
220   void RegisterNativeMethod(ArtMethod* method,
221                             const void* original_implementation,
222                             /*out*/void** new_implementation)
223       REQUIRES_SHARED(Locks::mutator_lock_);
224 
225   void MonitorContendedLocking(Monitor* m) REQUIRES_SHARED(Locks::mutator_lock_);
226   void MonitorContendedLocked(Monitor* m) REQUIRES_SHARED(Locks::mutator_lock_);
227   void ObjectWaitStart(Handle<mirror::Object> m, int64_t timeout)
228       REQUIRES_SHARED(Locks::mutator_lock_);
229   void MonitorWaitFinished(Monitor* m, bool timed_out)
230       REQUIRES_SHARED(Locks::mutator_lock_);
231 
232   void AddMonitorCallback(MonitorCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_);
233   void RemoveMonitorCallback(MonitorCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_);
234 
235   void ThreadParkStart(bool is_absolute, int64_t timeout) REQUIRES_SHARED(Locks::mutator_lock_);
236   void ThreadParkFinished(bool timed_out) REQUIRES_SHARED(Locks::mutator_lock_);
237   void AddParkCallback(ParkCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_);
238   void RemoveParkCallback(ParkCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_);
239 
240   // Returns true if any locals have changed. This is used to prevent OSRing frames that have
241   // some locals changed.
242   bool HaveLocalsChanged() REQUIRES_SHARED(Locks::mutator_lock_);
243 
244   void AddMethodInspectionCallback(MethodInspectionCallback* cb)
245       REQUIRES_SHARED(Locks::mutator_lock_);
246   void RemoveMethodInspectionCallback(MethodInspectionCallback* cb)
247       REQUIRES_SHARED(Locks::mutator_lock_);
248 
249   // DDMS callbacks
250   void DdmPublishChunk(uint32_t type, const ArrayRef<const uint8_t>& data)
251       REQUIRES_SHARED(Locks::mutator_lock_);
252 
253   void AddDdmCallback(DdmCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_);
254   void RemoveDdmCallback(DdmCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_);
255 
256   void SetCurrentProcessName(const std::string& process_name) REQUIRES_SHARED(Locks::mutator_lock_);
257   void AddApplication(const std::string& package_name) REQUIRES_SHARED(Locks::mutator_lock_);
258   void RemoveApplication(const std::string& package_name) REQUIRES_SHARED(Locks::mutator_lock_);
259   void SetWaitingForDebugger(bool waiting) REQUIRES_SHARED(Locks::mutator_lock_);
260   void SetUserId(int uid) REQUIRES_SHARED(Locks::mutator_lock_);
261 
262   void AddAppInfoCallback(AppInfoCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_);
263   void RemoveAppInfoCallback(AppInfoCallback* cb) REQUIRES_SHARED(Locks::mutator_lock_);
264 
265   void StartDebugger() REQUIRES_SHARED(Locks::mutator_lock_);
266   // NO_THREAD_SAFETY_ANALYSIS since this is only called when we are in the middle of shutting down
267   // and the mutator_lock_ is no longer acquirable.
268   void StopDebugger() NO_THREAD_SAFETY_ANALYSIS;
269   bool IsDebuggerConfigured() REQUIRES_SHARED(Locks::mutator_lock_);
270 
271   void AddDebuggerControlCallback(DebuggerControlCallback* cb)
272       REQUIRES_SHARED(Locks::mutator_lock_);
273   void RemoveDebuggerControlCallback(DebuggerControlCallback* cb)
274       REQUIRES_SHARED(Locks::mutator_lock_);
275 
276   void VisitReflectiveTargets(ReflectiveValueVisitor* visitor) REQUIRES(Locks::mutator_lock_);
277 
278   void AddReflectiveValueVisitCallback(ReflectiveValueVisitCallback* cb)
279       REQUIRES_SHARED(Locks::mutator_lock_);
280   void RemoveReflectiveValueVisitCallback(ReflectiveValueVisitCallback* cb)
281       REQUIRES_SHARED(Locks::mutator_lock_);
282 
283  private:
284   std::unique_ptr<ReaderWriterMutex> callback_lock_ BOTTOM_MUTEX_ACQUIRED_AFTER;
285 
286   std::vector<ThreadLifecycleCallback*> thread_callbacks_
287       GUARDED_BY(callback_lock_);
288   std::vector<ClassLoadCallback*> class_callbacks_
289       GUARDED_BY(callback_lock_);
290   std::vector<RuntimeSigQuitCallback*> sigquit_callbacks_
291       GUARDED_BY(callback_lock_);
292   std::vector<RuntimePhaseCallback*> phase_callbacks_
293       GUARDED_BY(callback_lock_);
294   std::vector<MethodCallback*> method_callbacks_
295       GUARDED_BY(callback_lock_);
296   std::vector<MonitorCallback*> monitor_callbacks_
297       GUARDED_BY(callback_lock_);
298   std::vector<ParkCallback*> park_callbacks_
299       GUARDED_BY(callback_lock_);
300   std::vector<MethodInspectionCallback*> method_inspection_callbacks_
301       GUARDED_BY(callback_lock_);
302   std::vector<DdmCallback*> ddm_callbacks_
303       GUARDED_BY(callback_lock_);
304   std::vector<AppInfoCallback*> appinfo_callbacks_ GUARDED_BY(callback_lock_);
305   std::vector<DebuggerControlCallback*> debugger_control_callbacks_
306       GUARDED_BY(callback_lock_);
307   std::vector<ReflectiveValueVisitCallback*> reflective_value_visit_callbacks_
308       GUARDED_BY(callback_lock_);
309 };
310 
311 }  // namespace art
312 
313 #endif  // ART_RUNTIME_RUNTIME_CALLBACKS_H_
314