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/macros.h"
23 #include "base/mutex.h"
24 #include "dex_file.h"
25 #include "handle.h"
26 
27 namespace art {
28 
29 namespace mirror {
30 class Class;
31 class ClassLoader;
32 }  // namespace mirror
33 
34 class ArtMethod;
35 class ClassLoadCallback;
36 class Thread;
37 class MethodCallback;
38 class ThreadLifecycleCallback;
39 
40 // Note: RuntimeCallbacks uses the mutator lock to synchronize the callback lists. A thread must
41 //       hold the exclusive lock to add or remove a listener. A thread must hold the shared lock
42 //       to dispatch an event. This setup is chosen as some clients may want to suspend the
43 //       dispatching thread or all threads.
44 //
45 //       To make this safe, the following restrictions apply:
46 //       * Only the owner of a listener may ever add or remove said listener.
47 //       * A listener must never add or remove itself or any other listener while running.
48 //       * It is the responsibility of the owner to not remove the listener while it is running
49 //         (and suspended).
50 //
51 //       The simplest way to satisfy these restrictions is to never remove a listener, and to do
52 //       any state checking (is the listener enabled) in the listener itself. For an example, see
53 //       Dbg.
54 
55 class RuntimeSigQuitCallback {
56  public:
~RuntimeSigQuitCallback()57   virtual ~RuntimeSigQuitCallback() {}
58 
59   virtual void SigQuit() REQUIRES_SHARED(Locks::mutator_lock_) = 0;
60 };
61 
62 class RuntimePhaseCallback {
63  public:
64   enum RuntimePhase {
65     kInitialAgents,   // Initial agent loading is done.
66     kStart,           // The runtime is started.
67     kInit,            // The runtime is initialized (and will run user code soon).
68     kDeath,           // The runtime just died.
69   };
70 
~RuntimePhaseCallback()71   virtual ~RuntimePhaseCallback() {}
72 
73   virtual void NextRuntimePhase(RuntimePhase phase) REQUIRES_SHARED(Locks::mutator_lock_) = 0;
74 };
75 
76 class RuntimeCallbacks {
77  public:
78   void AddThreadLifecycleCallback(ThreadLifecycleCallback* cb) REQUIRES(Locks::mutator_lock_);
79   void RemoveThreadLifecycleCallback(ThreadLifecycleCallback* cb) REQUIRES(Locks::mutator_lock_);
80 
81   void ThreadStart(Thread* self) REQUIRES_SHARED(Locks::mutator_lock_);
82   void ThreadDeath(Thread* self) REQUIRES_SHARED(Locks::mutator_lock_);
83 
84   void AddClassLoadCallback(ClassLoadCallback* cb) REQUIRES(Locks::mutator_lock_);
85   void RemoveClassLoadCallback(ClassLoadCallback* cb) REQUIRES(Locks::mutator_lock_);
86 
87   void ClassLoad(Handle<mirror::Class> klass) REQUIRES_SHARED(Locks::mutator_lock_);
88   void ClassPrepare(Handle<mirror::Class> temp_klass, Handle<mirror::Class> klass)
89       REQUIRES_SHARED(Locks::mutator_lock_);
90 
91   void AddRuntimeSigQuitCallback(RuntimeSigQuitCallback* cb)
92       REQUIRES(Locks::mutator_lock_);
93   void RemoveRuntimeSigQuitCallback(RuntimeSigQuitCallback* cb)
94       REQUIRES(Locks::mutator_lock_);
95 
96   void SigQuit() REQUIRES_SHARED(Locks::mutator_lock_);
97 
98   void AddRuntimePhaseCallback(RuntimePhaseCallback* cb)
99       REQUIRES(Locks::mutator_lock_);
100   void RemoveRuntimePhaseCallback(RuntimePhaseCallback* cb)
101       REQUIRES(Locks::mutator_lock_);
102 
103   void NextRuntimePhase(RuntimePhaseCallback::RuntimePhase phase)
104       REQUIRES_SHARED(Locks::mutator_lock_);
105 
106   void ClassPreDefine(const char* descriptor,
107                       Handle<mirror::Class> temp_class,
108                       Handle<mirror::ClassLoader> loader,
109                       const DexFile& initial_dex_file,
110                       const DexFile::ClassDef& initial_class_def,
111                       /*out*/DexFile const** final_dex_file,
112                       /*out*/DexFile::ClassDef const** final_class_def)
113       REQUIRES_SHARED(Locks::mutator_lock_);
114 
115   void AddMethodCallback(MethodCallback* cb) REQUIRES(Locks::mutator_lock_);
116   void RemoveMethodCallback(MethodCallback* cb) REQUIRES(Locks::mutator_lock_);
117 
118   void RegisterNativeMethod(ArtMethod* method,
119                             const void* original_implementation,
120                             /*out*/void** new_implementation)
121       REQUIRES_SHARED(Locks::mutator_lock_);
122 
123  private:
124   std::vector<ThreadLifecycleCallback*> thread_callbacks_
125       GUARDED_BY(Locks::mutator_lock_);
126   std::vector<ClassLoadCallback*> class_callbacks_
127       GUARDED_BY(Locks::mutator_lock_);
128   std::vector<RuntimeSigQuitCallback*> sigquit_callbacks_
129       GUARDED_BY(Locks::mutator_lock_);
130   std::vector<RuntimePhaseCallback*> phase_callbacks_
131       GUARDED_BY(Locks::mutator_lock_);
132   std::vector<MethodCallback*> method_callbacks_
133       GUARDED_BY(Locks::mutator_lock_);
134 };
135 
136 }  // namespace art
137 
138 #endif  // ART_RUNTIME_RUNTIME_CALLBACKS_H_
139