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