001    /*
002     *  This file is part of the Jikes RVM project (http://jikesrvm.org).
003     *
004     *  This file is licensed to You under the Eclipse Public License (EPL);
005     *  You may not use this file except in compliance with the License. You
006     *  may obtain a copy of the License at
007     *
008     *      http://www.opensource.org/licenses/eclipse-1.0.php
009     *
010     *  See the COPYRIGHT.txt file distributed with this work for information
011     *  regarding copyright ownership.
012     */
013    package org.jikesrvm.adaptive.measurements.listeners;
014    
015    import org.jikesrvm.adaptive.measurements.organizers.Organizer;
016    import org.vmmagic.pragma.Interruptible;
017    import org.vmmagic.pragma.Uninterruptible;
018    
019    /**
020     * A Listener object is invoked when online measurement information
021     * needs to be collected.
022     *
023     * This class does not define the update() method, the call back method from
024     * the runtime when a sample should be taken.
025     * The expectation is that immediately derived classes define an interface to
026     * the update() method from which classes may be further derived.
027     *
028     * CONSTRAINTS:
029     * Classes that are derived from Listener
030     * must be annotated as Uninterruptible to ensure that they
031     * are not interrupted by a thread switch.
032     * Since thread switching is disabled, listeners are
033     * expected to complete execution quickly, and therefore,
034     * must do a minimal amount of work.
035     */
036    @Uninterruptible
037    public abstract class Listener {
038    
039      /**
040       * Entry point to dump what has been collected.
041       */
042      @Interruptible
043      public abstract void report();
044    
045      /**
046       * Is the listener currently active (interested in getting "update" calls)
047       */
048      public final boolean isActive() { return active; }
049    
050      /**
051       * Transition listener to active state
052       */
053      public final void activate() { active = true; }
054    
055      /**
056       * Transition listener to passive state
057       */
058      public final void passivate() { active = false; }
059    
060      /**
061       * reset the listeners data structures
062       */
063      public abstract void reset();
064    
065      /**
066       * Organizer associated with this listener.
067       */
068      public final void setOrganizer(Organizer organizer) {
069        this.organizer = organizer;
070      }
071    
072      /**
073       * Wake up the organizer thread (if any) associated with the listener
074       */
075      public final void activateOrganizer() {
076        if (organizer != null) {
077          organizer.activate();
078        }
079      }
080    
081      // Is the listener active or passive?
082      private boolean active = false;
083      // My organizer.
084      private Organizer organizer;
085    
086    }