src/main/gov/nasa/jpf/vm/VMListener.java

   1 /*
   2  * Copyright (C) 2014, United States Government, as represented by the
   3  * Administrator of the National Aeronautics and Space Administration.
   4  * All rights reserved.
   5  *
   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
   9  *
  10  *        http://www.apache.org/licenses/LICENSE-2.0.
  11  *
  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.
  17  */
  18 package gov.nasa.jpf.vm;
  19
  20 import gov.nasa.jpf.JPFListener;
  21 import gov.nasa.jpf.jvm.ClassFile;
  22
  23 /**
  24  * interface to register for callbacks by the VM
  25  * Observer role in equally named pattern
  26  *
  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
  31  * by JPF
  32  */
  33 public interface VMListener extends JPFListener {
  34
  35   /**
  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
  38    */
  39   void vmInitialized (VM vm);
  40
  41   /**
  42    * VM is about to execute the next instruction
  43    */
  44   void executeInstruction (VM vm, ThreadInfo currentThread, Instruction instructionToExecute);
  45
  46   /**
  47    * VM has executed the next instruction
  48    * (can be used to analyze branches, monitor PUTFIELD / GETFIELD and
  49    * INVOKExx / RETURN instructions)
  50    */
  51   void instructionExecuted (VM vm, ThreadInfo currentThread, Instruction nextInstruction, Instruction executedInstruction);
  52
  53   /**
  54    * new Thread entered run() method
  55    */
  56   void threadStarted (VM vm, ThreadInfo startedThread);
  57
  58   /**
  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
  62    */
  63   void threadBlocked (VM vm, ThreadInfo blockedThread, ElementInfo lock);
  64
  65   /**
  66    * thread is waiting for signal
  67    */
  68   void threadWaiting (VM vm, ThreadInfo waitingThread);
  69
  70   /**
  71    * thread got notified
  72    */
  73   void threadNotified (VM vm, ThreadInfo notifiedThread);
  74
  75   /**
  76    * thread got interrupted
  77    */
  78   void threadInterrupted (VM vm, ThreadInfo interruptedThread);
  79
  80   /**
  81    * Thread exited run() method
  82    */
  83   void threadTerminated (VM vm, ThreadInfo terminatedThread);
  84
  85   /**
  86    * new thread was scheduled by VM
  87    */
  88   void threadScheduled (VM vm, ThreadInfo scheduledThread); // this might go into the choice generator notifications
  89
  90   /**
  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
  94    */
  95   public void loadClass (VM vm, ClassFile cf);
  96
  97   /**
  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
 104    */
 105   void classLoaded (VM vm, ClassInfo loadedClass);
 106
 107   /**
 108    * new object was created
 109    */
 110   void objectCreated (VM vm, ThreadInfo currentThread, ElementInfo newObject);
 111
 112   /**
 113    * object was garbage collected (after potential finalization)
 114    */
 115   void objectReleased (VM vm, ThreadInfo currentThread, ElementInfo releasedObject);
 116
 117   /**
 118    * notify if an object lock was taken (this includes automatic
 119    * surrender during a wait())
 120    */
 121   void objectLocked (VM vm, ThreadInfo currentThread, ElementInfo lockedObject);
 122
 123   /**
 124    * notify if an object lock was released (this includes automatic
 125    * reacquisition after a notify())
 126    */
 127   void objectUnlocked (VM vm, ThreadInfo currentThread, ElementInfo unlockedObject);
 128
 129   /**
 130    * notify if a wait() is executed
 131    */
 132   void objectWait (VM vm, ThreadInfo currentThread, ElementInfo waitingObject);
 133
 134   /**
 135    * notify if an object notifies a single waiter
 136    */
 137   void objectNotify (VM vm, ThreadInfo currentThread, ElementInfo notifyingObject);
 138
 139   /**
 140    * notify if an object notifies all waiters
 141    */
 142   void objectNotifyAll (VM vm, ThreadInfo currentThread, ElementInfo notifyingObject);
 143
 144
 145   /**
 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
 148    */
 149   void objectExposed (VM vm, ThreadInfo currentThread, ElementInfo fieldOwnerObject, ElementInfo exposedObject);
 150
 151   /**
 152    * object fields accessed by more than one live thread
 153    */
 154   void objectShared (VM vm, ThreadInfo currentThread, ElementInfo sharedObject);
 155
 156
 157   void gcBegin (VM vm);
 158
 159   void gcEnd (VM vm);
 160
 161   /**
 162    * exception was thrown
 163    */
 164   void exceptionThrown (VM vm, ThreadInfo currentThread, ElementInfo thrownException);
 165
 166   /**
 167    * exception causes top frame to be purged
 168    */
 169   void exceptionBailout (VM vm, ThreadInfo currentThread);
 170
 171   /**
 172    * exception handled by current top frame
 173    */
 174   void exceptionHandled (VM vm, ThreadInfo currentThread);
 175
 176   /**
 177    * next ChoiceGenerator was registered, which means this is the end of the current transition
 178    *
 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)
 183    */
 184   void choiceGeneratorRegistered (VM vm, ChoiceGenerator<?> nextCG, ThreadInfo currentThread, Instruction executedInstruction);
 185
 186   /**
 187    * a new ChoiceGenerator was set, which means we are at the beginning of a new transition.
 188    *
 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)
 191    */
 192   void choiceGeneratorSet (VM vm, ChoiceGenerator<?> newCG);
 193
 194   /**
 195    * the next choice was requested from a previously registered ChoiceGenerator
 196    *
 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)
 199    */
 200   void choiceGeneratorAdvanced (VM vm, ChoiceGenerator<?> currentCG);
 201
 202   /**
 203    * a ChoiceGnerator has returned all his choices
 204    *
 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)
 207    */
 208   void choiceGeneratorProcessed (VM vm, ChoiceGenerator<?> processedCG);
 209
 210   /**
 211    * method body was entered. This is notified before the first instruction
 212    * is executed
 213    */
 214   void methodEntered (VM vm, ThreadInfo currentThread, MethodInfo enteredMethod);
 215
 216   /**
 217    * method body was left. This is notified after the last instruction had
 218    * been executed
 219    * NOTE - this is also notified when a StackFrame is dropped due to unhandled exceptions
 220    */
 221   void methodExited (VM vm, ThreadInfo currentThread, MethodInfo exitedMethod);
 222
 223 }
 224