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