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 */
013package org.jikesrvm.adaptive.measurements.listeners;
014
015import org.jikesrvm.adaptive.measurements.organizers.Organizer;
016import org.vmmagic.pragma.Interruptible;
017import org.vmmagic.pragma.Uninterruptible;
018
019/**
020 * A Listener object is invoked when online measurement information
021 * needs to be collected.
022 * <p>
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 * <p>
028 * CONSTRAINTS:
029 * Classes that are derived from Listener
030 * must be annotated as {@link 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
037public 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   * @return whether the listener is currently active (interested
047   *  in getting "update" calls)
048   */
049  public final boolean isActive() {
050    return active;
051  }
052
053  /**
054   * Transition listener to active state
055   */
056  public final void activate() {
057    active = true;
058  }
059
060  /**
061   * Transition listener to passive state
062   */
063  public final void passivate() {
064    active = false;
065  }
066
067  /**
068   * Reset the listeners data structures in preparation of a new sampling
069   * window. This is called by the organizer after processing the samples
070   * from the old sampling window.
071   */
072  public abstract void reset();
073
074  public final void setOrganizer(Organizer organizer) {
075    this.organizer = organizer;
076  }
077
078  /**
079   * Wake up the organizer thread (if any) associated with the listener
080   */
081  public final void activateOrganizer() {
082    if (organizer != null) {
083      organizer.activate();
084    }
085  }
086
087  /** Is the listener active or passive? */
088  private boolean active = false;
089  /**  the associated organizer */
090  private Organizer organizer;
091
092}