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