2 * Copyright (C) 2014, United States Government, as represented by the
3 * Administrator of the National Aeronautics and Space Administration.
6 * The Java Pathfinder core (jpf-core) platform is licensed under the
7 * Apache License, Version 2.0 (the "License"); you may not use this file except
8 * in compliance with the License. You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0.
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
18 package gov.nasa.jpf.vm;
20 import gov.nasa.jpf.JPFListener;
21 import gov.nasa.jpf.jvm.ClassFile;
24 * interface to register for callbacks by the VM
25 * Observer role in equally named pattern
27 * Note that we only have notifications for generic events, NOT for conditions that
28 * are property specific, and especially nothing that is just triggered from an extension.
29 * If listeners are used to implement high level properties, the notifications should be
30 * used to implement properties, not to report some property violation that was detected
33 public interface VMListener extends JPFListener {
36 * VM got initialized (but search is not yet running). This can be used to
37 * do type initialization in listeners, since the ClassLoader mechanism is now functional
39 void vmInitialized (VM vm);
42 * VM is about to execute the next instruction
44 void executeInstruction (VM vm, ThreadInfo currentThread, Instruction instructionToExecute);
47 * VM has executed the next instruction
48 * (can be used to analyze branches, monitor PUTFIELD / GETFIELD and
49 * INVOKExx / RETURN instructions)
51 void instructionExecuted (VM vm, ThreadInfo currentThread, Instruction nextInstruction, Instruction executedInstruction);
54 * new Thread entered run() method
56 void threadStarted (VM vm, ThreadInfo startedThread);
59 * thread waits to acquire a lock
60 // NOTE: vm.getLastThreadInfo() does NOT have to be the running thread, as this
61 // notification can occur as a result of a lock operation in the current thread
63 void threadBlocked (VM vm, ThreadInfo blockedThread, ElementInfo lock);
66 * thread is waiting for signal
68 void threadWaiting (VM vm, ThreadInfo waitingThread);
73 void threadNotified (VM vm, ThreadInfo notifiedThread);
76 * thread got interrupted
78 void threadInterrupted (VM vm, ThreadInfo interruptedThread);
81 * Thread exited run() method
83 void threadTerminated (VM vm, ThreadInfo terminatedThread);
86 * new thread was scheduled by VM
88 void threadScheduled (VM vm, ThreadInfo scheduledThread); // this might go into the choice generator notifications
91 * a new classfile is about to be parsed. This notification allows replacement
92 * of the related classfile data via ClassFile.{get/set}Data() and can be
93 * used to do on-the-fly classfile instrumentation with 3rd party libraries
95 public void loadClass (VM vm, ClassFile cf);
98 * new class was loaded. This is notified after the ClassInfo has been
99 * instantiated, but before the class object is initialized, i.e. clinit
100 * is called. The main use for this notification is to identify and
101 * store ClassInfos, MethodInfos, FieldInfos or Instructions that are
102 * used by listeners etc. in order to enable efficient identify based filters
103 * in the performance critical instruction notifications
105 void classLoaded (VM vm, ClassInfo loadedClass);
108 * new object was created
110 void objectCreated (VM vm, ThreadInfo currentThread, ElementInfo newObject);
113 * object was garbage collected (after potential finalization)
115 void objectReleased (VM vm, ThreadInfo currentThread, ElementInfo releasedObject);
118 * notify if an object lock was taken (this includes automatic
119 * surrender during a wait())
121 void objectLocked (VM vm, ThreadInfo currentThread, ElementInfo lockedObject);
124 * notify if an object lock was released (this includes automatic
125 * reacquisition after a notify())
127 void objectUnlocked (VM vm, ThreadInfo currentThread, ElementInfo unlockedObject);
130 * notify if a wait() is executed
132 void objectWait (VM vm, ThreadInfo currentThread, ElementInfo waitingObject);
135 * notify if an object notifies a single waiter
137 void objectNotify (VM vm, ThreadInfo currentThread, ElementInfo notifyingObject);
140 * notify if an object notifies all waiters
142 void objectNotifyAll (VM vm, ThreadInfo currentThread, ElementInfo notifyingObject);
146 * object becomes reachable through a shared reference
147 * 'sharedObject' is the (already shared) owner of the field to which the (yet unshared) 'exposedObject' reference got assigned
149 void objectExposed (VM vm, ThreadInfo currentThread, ElementInfo fieldOwnerObject, ElementInfo exposedObject);
152 * object fields accessed by more than one live thread
154 void objectShared (VM vm, ThreadInfo currentThread, ElementInfo sharedObject);
157 void gcBegin (VM vm);
162 * exception was thrown
164 void exceptionThrown (VM vm, ThreadInfo currentThread, ElementInfo thrownException);
167 * exception causes top frame to be purged
169 void exceptionBailout (VM vm, ThreadInfo currentThread);
172 * exception handled by current top frame
174 void exceptionHandled (VM vm, ThreadInfo currentThread);
177 * next ChoiceGenerator was registered, which means this is the end of the current transition
179 * the reason why we have this in addition to the choiceGeneratorSet is that listeners
180 * can reset the registered CG and so force the current transition to continue (although the
181 * listener in this case has to make sure the operand stack is in a consistent state for
182 * continued execution because there might be a bottom half of an Instruction.execute() missing)
184 void choiceGeneratorRegistered (VM vm, ChoiceGenerator<?> nextCG, ThreadInfo currentThread, Instruction executedInstruction);
187 * a new ChoiceGenerator was set, which means we are at the beginning of a new transition.
189 * NOTE - this notification happens before the KernelState is stored, i.e. listeners are NOT
190 * allowed to alter the KernelState (e.g. by changing field values or thread states)
192 void choiceGeneratorSet (VM vm, ChoiceGenerator<?> newCG);
195 * the next choice was requested from a previously registered ChoiceGenerator
197 * NOTE - this notification happens before the KernelState is stored, i.e. listeners are NOT
198 * allowed to alter the KernelState (e.g. by changing field values or thread states)
200 void choiceGeneratorAdvanced (VM vm, ChoiceGenerator<?> currentCG);
203 * a ChoiceGnerator has returned all his choices
205 * NOTE - this notification happens before the KernelState is stored, i.e. listeners are NOT
206 * allowed to alter the KernelState (e.g. by changing field values or thread states)
208 void choiceGeneratorProcessed (VM vm, ChoiceGenerator<?> processedCG);
211 * method body was entered. This is notified before the first instruction
214 void methodEntered (VM vm, ThreadInfo currentThread, MethodInfo enteredMethod);
217 * method body was left. This is notified after the last instruction had
219 * NOTE - this is also notified when a StackFrame is dropped due to unhandled exceptions
221 void methodExited (VM vm, ThreadInfo currentThread, MethodInfo exitedMethod);