1fb3fb4f3Stomee /* 2fb3fb4f3Stomee * CDDL HEADER START 3fb3fb4f3Stomee * 4fb3fb4f3Stomee * The contents of this file are subject to the terms of the 5fb3fb4f3Stomee * Common Development and Distribution License (the "License"). 6fb3fb4f3Stomee * You may not use this file except in compliance with the License. 7fb3fb4f3Stomee * 8fb3fb4f3Stomee * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9fb3fb4f3Stomee * or http://www.opensolaris.org/os/licensing. 10fb3fb4f3Stomee * See the License for the specific language governing permissions 11fb3fb4f3Stomee * and limitations under the License. 12fb3fb4f3Stomee * 13fb3fb4f3Stomee * When distributing Covered Code, include this CDDL HEADER in each 14fb3fb4f3Stomee * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15fb3fb4f3Stomee * If applicable, add the following below this CDDL HEADER, with the 16fb3fb4f3Stomee * fields enclosed by brackets "[]" replaced with your own identifying 17fb3fb4f3Stomee * information: Portions Copyright [yyyy] [name of copyright owner] 18fb3fb4f3Stomee * 19fb3fb4f3Stomee * CDDL HEADER END 20fb3fb4f3Stomee */ 21fb3fb4f3Stomee 22fb3fb4f3Stomee /* 23fb3fb4f3Stomee * Copyright 2006 Sun Microsystems, Inc. All rights reserved. 24fb3fb4f3Stomee * Use is subject to license terms. 25fb3fb4f3Stomee */ 26fb3fb4f3Stomee package org.opensolaris.os.dtrace; 27fb3fb4f3Stomee 28fb3fb4f3Stomee import java.util.EventListener; 29fb3fb4f3Stomee 30fb3fb4f3Stomee /** 31fb3fb4f3Stomee * Listener for data generated by a single DTrace {@link Consumer}. 32fb3fb4f3Stomee * 33fb3fb4f3Stomee * @author Tom Erickson 34fb3fb4f3Stomee */ 35fb3fb4f3Stomee public interface ConsumerListener extends EventListener { 36fb3fb4f3Stomee /** 37fb3fb4f3Stomee * Called whenever a DTrace probe fires (that is, once for each 38fb3fb4f3Stomee * instance of {@link ProbeData} generated by DTrace). Identifies 39fb3fb4f3Stomee * the probe and provides data generated by the probe's actions. To 40fb3fb4f3Stomee * terminate the consumer in the event of unexpected data, throw a 41fb3fb4f3Stomee * {@link ConsumerException} from this method. 42fb3fb4f3Stomee * 43fb3fb4f3Stomee * @throws ConsumerException if the implementation should terminate 44fb3fb4f3Stomee * the running consumer 45fb3fb4f3Stomee */ dataReceived(DataEvent e)46fb3fb4f3Stomee public void dataReceived(DataEvent e) throws ConsumerException; 47fb3fb4f3Stomee 48fb3fb4f3Stomee /** 49fb3fb4f3Stomee * Called when traced data is dropped because of inadequate buffer 50fb3fb4f3Stomee * space. To terminate the consumer in the event of a drop, throw 51fb3fb4f3Stomee * a {@link ConsumerException} from this method. 52fb3fb4f3Stomee * 53fb3fb4f3Stomee * @throws ConsumerException if the implementation should terminate 54fb3fb4f3Stomee * the running consumer 55fb3fb4f3Stomee */ dataDropped(DropEvent e)56fb3fb4f3Stomee public void dataDropped(DropEvent e) throws ConsumerException; 57fb3fb4f3Stomee 58fb3fb4f3Stomee /** 59fb3fb4f3Stomee * Called when an error is encountered in the native DTrace library 60fb3fb4f3Stomee * while tracing probe data. To terminate the consumer, throw a 61fb3fb4f3Stomee * {@link ConsumerException} from this method. 62fb3fb4f3Stomee * 63fb3fb4f3Stomee * @throws ConsumerException if the implementation should terminate 64fb3fb4f3Stomee * the running consumer 65fb3fb4f3Stomee */ errorEncountered(ErrorEvent e)66fb3fb4f3Stomee public void errorEncountered(ErrorEvent e) throws ConsumerException; 67fb3fb4f3Stomee 68fb3fb4f3Stomee /** 69fb3fb4f3Stomee * Called when the state of a target process changes. To terminate 70fb3fb4f3Stomee * the consumer in the event of unexpected process state, throw a 71fb3fb4f3Stomee * {@link ConsumerException} from this method. 72fb3fb4f3Stomee * 73fb3fb4f3Stomee * @throws ConsumerException if the implementation should terminate 74fb3fb4f3Stomee * the running consumer 75fb3fb4f3Stomee * @see Consumer#createProcess(String command) 76fb3fb4f3Stomee * @see Consumer#grabProcess(int pid) 77fb3fb4f3Stomee */ processStateChanged(ProcessEvent e)78fb3fb4f3Stomee public void processStateChanged(ProcessEvent e) throws ConsumerException; 79fb3fb4f3Stomee 80fb3fb4f3Stomee /** 81fb3fb4f3Stomee * Called once when the source {@link Consumer} is successfully 82fb3fb4f3Stomee * started in response to {@link Consumer#go()}. 83fb3fb4f3Stomee * 84fb3fb4f3Stomee * @see #consumerStopped(ConsumerEvent e) 85fb3fb4f3Stomee */ consumerStarted(ConsumerEvent e)86fb3fb4f3Stomee public void consumerStarted(ConsumerEvent e); 87fb3fb4f3Stomee 88fb3fb4f3Stomee /** 89fb3fb4f3Stomee * Called once when the source {@link Consumer} is stopped, 90fb3fb4f3Stomee * indicating that this listener should expect no further events. 91382dbd46Stomee * Guaranteed to be called whether the consumer was stopped by 92382dbd46Stomee * request (by calling {@link Consumer#stop()} or {@link 93382dbd46Stomee * Consumer#abort()}), terminated normally as a result of the DTrace 94382dbd46Stomee * {@code exit()} action (see <a 95*3a931819SPeter Tribble * href=http://dtrace.org/guide/chp-actsub.html#chp-actsub-5> 96*3a931819SPeter Tribble * <b>{@code exit()}</b></a> in the <b>Special Actions</b> section of the 97*3a931819SPeter Tribble * <b>Actions and Subroutines</b> chapter of the <i>Dynamic 98382dbd46Stomee * Tracing Guide</i>) or after the completion of all target 99382dbd46Stomee * processes, or terminated abnormally because of an exception. It 100382dbd46Stomee * is necessary to call {@link Consumer#close()} to release any 101382dbd46Stomee * system resources still held by the stopped consumer. 102fb3fb4f3Stomee * 103fb3fb4f3Stomee * @see #consumerStarted(ConsumerEvent e) 104fb3fb4f3Stomee */ consumerStopped(ConsumerEvent e)105fb3fb4f3Stomee public void consumerStopped(ConsumerEvent e); 106fb3fb4f3Stomee 107fb3fb4f3Stomee /** 108fb3fb4f3Stomee * Called when the source {@link Consumer} wakes up to process its 109fb3fb4f3Stomee * buffer of traced probe data. 110fb3fb4f3Stomee * 111fb3fb4f3Stomee * @see #intervalEnded(ConsumerEvent e) 112fb3fb4f3Stomee */ intervalBegan(ConsumerEvent e)113fb3fb4f3Stomee public void intervalBegan(ConsumerEvent e); 114fb3fb4f3Stomee 115fb3fb4f3Stomee /** 116fb3fb4f3Stomee * Called when the source {@link Consumer} finishes processing its 117fb3fb4f3Stomee * buffer of traced probe data and is about to sleep until the next 118fb3fb4f3Stomee * interval. The rate of consumption may be controlled with the 119fb3fb4f3Stomee * {@link Option#switchrate switchrate} and {@link Option#aggrate 120fb3fb4f3Stomee * aggrate} options (see {@link Consumer#setOption(String option, 121fb3fb4f3Stomee * String value)}). 122fb3fb4f3Stomee * 123fb3fb4f3Stomee * @see #intervalBegan(ConsumerEvent e) 124fb3fb4f3Stomee */ intervalEnded(ConsumerEvent e)125fb3fb4f3Stomee public void intervalEnded(ConsumerEvent e); 126fb3fb4f3Stomee } 127