org.opensolaris.os.dtrace
Class LocalConsumer

java.lang.Object
  extended by org.opensolaris.os.dtrace.LocalConsumer
All Implemented Interfaces:
Consumer

public class LocalConsumer
extends java.lang.Object
implements Consumer

Interface to the native DTrace library, each instance is a single DTrace consumer.


Nested Class Summary
 
Nested classes/interfaces inherited from interface org.opensolaris.os.dtrace.Consumer
Consumer.OpenFlag
 
Field Summary
protected  ExceptionHandler exceptionHandler
           
protected  javax.swing.event.EventListenerList listenerList
           
 
Constructor Summary
LocalConsumer()
          Creates a consumer that interacts with the native DTrace library on the local system.
 
Method Summary
 void abort()
          Aborts the background thread started by Consumer.go().
 void addConsumerListener(ConsumerListener l)
          Adds a listener for probe data generated by this consumer.
 void close()
          Closes an open consumer and releases the system resources it was holding.
 Program compile(java.io.File program, java.lang.String... macroArgs)
          Compiles the given D program file.
 Program compile(java.lang.String program, java.lang.String... macroArgs)
          Compiles the given D program string.
 int createProcess(java.lang.String command)
          Creates a process by executing the given command on the system and returns the created process ID.
protected  java.lang.Thread createThread()
          Creates the background thread started by go() to run this consumer.
 void enable()
          Enables all DTrace probes compiled by this consumer.
 void enable(Program program)
          Enables DTrace probes matching the given program and attaches information about those probes to the given program.
protected  void finalize()
          Ensures that the close() method of this consumer has been called before it is garbage-collected.
protected  void fireConsumerStarted(ConsumerEvent e)
           
protected  void fireConsumerStopped(ConsumerEvent e)
           
protected  void fireDataDropped(DropEvent e)
           
protected  void fireDataReceived(DataEvent e)
           
protected  void fireErrorEncountered(ErrorEvent e)
           
protected  void fireIntervalBegan(ConsumerEvent e)
           
protected  void fireIntervalEnded(ConsumerEvent e)
           
protected  void fireProcessStateChanged(ProcessEvent e)
           
 Aggregate getAggregate()
          Gets a snapshot of all aggregations except those that have already been captured in a PrintaRecord.
 Aggregate getAggregate(java.util.Set<java.lang.String> includedAggregationNames)
          Gets a snapshot of all the specified aggregations except those that have already been captured in a PrintaRecord.
 Aggregate getAggregate(java.util.Set<java.lang.String> includedAggregationNames, java.util.Set<java.lang.String> clearedAggregationNames)
          Gets a snapshot of all the specified aggregations except those that have already been captured in a PrintaRecord, with the side effect of atomically clearing any subset of those aggregations.
 long getOption(java.lang.String option)
          Gets the value of a DTrace option.
 void getProgramInfo(Program program)
          Attaches information about matching DTrace probes to the given program.
 java.lang.String getVersion()
          Gets the version of the native DTrace library.
 void go()
          Begin tracing and start a background thread to consume generated probe data.
 void go(ExceptionHandler h)
          Begin tracing and start a background thread to consume generated probe data.
 void grabProcess(int pid)
          Grabs the specified process and caches its symbol tables.
 boolean isClosed()
          Reports whether or not this consumer is closed.
 boolean isEnabled()
          Reports whether or not it is valid to call Consumer.go().
 boolean isOpen()
          Reports whether or not this consumer is open.
 boolean isRunning()
          Reports whether or not this consumer is running.
 java.util.List<Probe> listProbeDetail(ProbeDescription filter)
          Lists probes that match the given probe description and includes detail such as stability information about each listed probe.
 java.util.List<ProbeDescription> listProbes(ProbeDescription filter)
          Lists probes that match the given probe description.
 java.util.List<Probe> listProgramProbeDetail(Program program)
          Lists probes that match the given compiled program and includes detail such as stability information about each listed probe.
 java.util.List<ProbeDescription> listProgramProbes(Program program)
          Lists probes that match the given compiled program.
 java.lang.String lookupKernelFunction(int address)
          Gets the kernel function name for the given 32-bit kernel address.
 java.lang.String lookupKernelFunction(long address)
          Gets the kernel function name for the given 64-bit kernel address.
 java.lang.String lookupUserFunction(int pid, int address)
          Gets the user function name for the given 32-bit user address and process ID.
 java.lang.String lookupUserFunction(int pid, long address)
          Gets the user function name for the given 64-bit user address and process ID.
 void open(Consumer.OpenFlag... flags)
          Opens this DTrace consumer.
 void removeConsumerListener(ConsumerListener l)
          Removes a listener for probe data generated by this consumer.
 void setOption(java.lang.String option)
          Sets a boolean option.
 void setOption(java.lang.String option, java.lang.String value)
          Sets the value of a DTrace option.
 void stop()
          Stops all tracing, as well as the background thread started by Consumer.go() to consume generated probe data.
 java.lang.String toString()
          Gets a string representation of this consumer useful for logging and not intended for display.
 void unsetOption(java.lang.String option)
          Unsets a boolean option.
protected  void work()
          Called in the runnable target of the thread returned by createThread() to run this DTrace consumer.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

listenerList

protected javax.swing.event.EventListenerList listenerList

exceptionHandler

protected ExceptionHandler exceptionHandler
Constructor Detail

LocalConsumer

public LocalConsumer()
Creates a consumer that interacts with the native DTrace library on the local system.

Method Detail

open

public void open(Consumer.OpenFlag... flags)
          throws DTraceException
Description copied from interface: Consumer
Opens this DTrace consumer. Optional flags indicate behaviors that can only be set at the time of opening. Most optional behaviors are set using setOption() after opening the consumer. In the great majority of cases, the consumer is opened without specifying any flags:
          consumer.open();
Subsequent calls to set options, compile DTrace programs, enable probes, and run this consumer may be made from any thread.

Specified by:
open in interface Consumer
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.compile(File program, String[] macroArgs), Consumer.compile(String program, String[] macroArgs), Consumer.enable(), Consumer.go()

compile

public Program compile(java.lang.String program,
                       java.lang.String... macroArgs)
                throws DTraceException
Description copied from interface: Consumer
Compiles the given D program string. Optional macro arguments replace corresponding numbered macro variables in the D program starting at $1.

Specified by:
compile in interface Consumer
Parameters:
program - program string
macroArgs - macro substitutions for $n placeholders embedded in the given D program: macroArgs[0] replaces all occurrences of $1, macroArgs[1] replaces all occurrences of $2, and so on. $0 is automatically replaced by the executable name and should not be included in the macroArgs parameter. See the Macro Arguments section of the Scripting chapter of the Solaris Dynamic Tracing Guide.
Returns:
a non-null Program identifier that may be passed to enable()
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.compile(File program, String[] macroArgs)

compile

public Program compile(java.io.File program,
                       java.lang.String... macroArgs)
                throws DTraceException,
                       java.io.IOException,
                       java.lang.SecurityException
Description copied from interface: Consumer
Compiles the given D program file. Optional macro arguments replace corresponding numbered macro variables in the D program starting at $1.

Specified by:
compile in interface Consumer
Parameters:
program - program file
macroArgs - macro substitutions for $n placeholders embedded in the given D program: macroArgs[0] replaces all occurrences of $1, macroArgs[1] replaces all occurrences of $2, and so on. $0 is automatically set to the name of the given file and should not be included in the macroArgs parameter. See the Macro Arguments section of the Scripting chapter of the Solaris Dynamic Tracing Guide.
Returns:
a non-null Program identifier that may be passed to enable()
Throws:
DTraceException - if an exception occurs in the native DTrace library
java.io.FileNotFoundException - if the given program file cannot be opened
java.io.IOException - if an I/O error occurs while reading the contents of the given program file
java.lang.SecurityException - if a security manager exists and its checkRead() method denies read access to the file
See Also:
Consumer.compile(String program, String[] macroArgs)

enable

public void enable()
            throws DTraceException
Description copied from interface: Consumer
Enables all DTrace probes compiled by this consumer. Call enable() with no argument to enable everything this consumer has compiled so far (most commonly a single program, the only one to be compiled). Call with one Program at a time if you need information about enabled probes specific to each program.

Specified by:
enable in interface Consumer
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.enable(Program program)

enable

public void enable(Program program)
            throws DTraceException
Description copied from interface: Consumer
Enables DTrace probes matching the given program and attaches information about those probes to the given program. A probe matched multiple times (within the same D program or in multiple D programs) triggers the actions associated with each matching occurrence every time that probe fires.

Specified by:
enable in interface Consumer
Parameters:
program - A Program identifier returned by compile(String program, ...) or compile(File program, ...): If the given program is null, the call has the same behavior as Consumer.enable() with no argument; if the given program is non-null, the call enables only those probes matching that program. In the latter case, the Program parameter is modified as a way of passing back information about the given program and its matching probes, including program stability.
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.compile(String program, String[] macroArgs), Consumer.compile(File program, String[] macroArgs), Consumer.enable(), Consumer.getProgramInfo(Program program)

getProgramInfo

public void getProgramInfo(Program program)
                    throws DTraceException
Description copied from interface: Consumer
Attaches information about matching DTrace probes to the given program. Attaches the same information to the given program as that attached by Consumer.enable(Program program) but without enabling the probes.

Specified by:
getProgramInfo in interface Consumer
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.compile(String program, String[] macroArgs), Consumer.compile(File program, String[] macroArgs), Consumer.enable(Program program)

setOption

public void setOption(java.lang.String option)
               throws DTraceException
Description copied from interface: Consumer
Sets a boolean option.

Specified by:
setOption in interface Consumer
Throws:
DTraceException - if a value is expected for the given option, or if the option is otherwise invalid
See Also:
Consumer.setOption(String option, String value), Consumer.unsetOption(String option)

unsetOption

public void unsetOption(java.lang.String option)
                 throws DTraceException
Description copied from interface: Consumer
Unsets a boolean option.

Specified by:
unsetOption in interface Consumer
Throws:
DTraceException - if the given option is not a boolean option, or if the option is otherwise invalid
See Also:
Consumer.setOption(String option)

setOption

public void setOption(java.lang.String option,
                      java.lang.String value)
               throws DTraceException
Description copied from interface: Consumer
Sets the value of a DTrace option. If the given option affects compile-time behavior, it must be set before calling compile(String program, ...) or compile(File program, ...) in order to have an effect on compilation. Some runtime options including switchrate and aggrate are settable while a consumer is running; others must be set before calling Consumer.go(). See the Options and Tunables chapter of the Solaris Dynamic Guide for information about specific options.

Specified by:
setOption in interface Consumer
Throws:
DTraceException - for any of the following:
  • The option is invalid
  • The value is invalid for the given option
  • go() has been called to start this consumer, and the option is not settable on a running consumer (some runtime options, including switchrate and aggrate are settable while the consumer is running)
See Also:
Consumer.open(OpenFlag[] flags), Consumer.getOption(String option), Option

getOption

public long getOption(java.lang.String option)
               throws DTraceException
Description copied from interface: Consumer
Gets the value of a DTrace option.

Specified by:
getOption in interface Consumer
Returns:
the value of the given DTrace option: If the given option is a boolean option and is currently unset, the returned value is Option.UNSET. If the given option is a size option, the returned value is in bytes. If the given option is a time option, the returned value is in nanoseconds. If the given option is bufpolicy, the returned value is one of BUFPOLICY_RING, BUFPOLICY_FILL, or BUFPOLICY_SWITCH. If the given option is bufresize, the returned value is one of BUFRESIZE_AUTO or BUFRESIZE_MANUAL.
Throws:
DTraceException - if the given option is invalid
See Also:
Consumer.setOption(String option), Consumer.unsetOption(String option), Consumer.setOption(String option, String value), Option

isOpen

public final boolean isOpen()
Description copied from interface: Consumer
Reports whether or not this consumer is open.

Specified by:
isOpen in interface Consumer
Returns:
true if and only if open() has been called on this consumer and Consumer.close() has not

isEnabled

public final boolean isEnabled()
Description copied from interface: Consumer
Reports whether or not it is valid to call Consumer.go().

Specified by:
isEnabled in interface Consumer
Returns:
true if and only if at least one program has been compiled, all compiled programs have been enabled, go() has not already been called, and Consumer.close() has not been called

isRunning

public final boolean isRunning()
Description copied from interface: Consumer
Reports whether or not this consumer is running. There may be a delay after calling Consumer.go() before this consumer actually starts running (listeners are notified by the consumerStarted() method).

Specified by:
isRunning in interface Consumer
Returns:
true if this consumer is running, false otherwise

isClosed

public final boolean isClosed()
Description copied from interface: Consumer
Reports whether or not this consumer is closed. A closed consumer cannot be reopened.

Note that a closed consumer is different from a consumer that has not yet been opened.

Specified by:
isClosed in interface Consumer
Returns:
true if Consumer.close() has been called on this consumer, false otherwise

work

protected final void work()
Called in the runnable target of the thread returned by createThread() to run this DTrace consumer.

See Also:
createThread()

createThread

protected java.lang.Thread createThread()
Creates the background thread started by go() to run this consumer. Override this method if you need to set non-default Thread options or create the thread in a ThreadGroup. If you don't need to create the thread yourself, set the desired options on super.createThread() before returning it. Otherwise, the Runnable target of the created thread must call work() in order to run this DTrace consumer. For example, to modify the default background consumer thread:

        protected Thread
        createThread()
        {
                Thread t = super.createThread();
                t.setPriority(Thread.MIN_PRIORITY);
                return t;
        }
 
Or if you need to create your own thread:

        protected Thread
        createThread()
        {
                Runnable target = new Runnable() {
                        public void run() {
                                work();
                        }
                };
                String name = "Consumer " + UserApplication.sequence++;
                Thread t = new Thread(UserApplication.threadGroup,
                        target, name);
                return t;
        }
 
Do not start the returned thread, otherwise go() will throw an IllegalThreadStateException when it tries to start the returned thread a second time.


go

public void go()
        throws DTraceException
Description copied from interface: Consumer
Begin tracing and start a background thread to consume generated probe data.

Specified by:
go in interface Consumer
Throws:
java.lang.IllegalThreadStateException - if a subclass calls Thread.start() on the value of createThread()
DTraceException - if an exception occurs in the native DTrace library
See Also:
createThread()

go

public void go(ExceptionHandler h)
        throws DTraceException
Description copied from interface: Consumer
Begin tracing and start a background thread to consume generated probe data. Handle any exception thrown in the consumer thread with the given handler.

Specified by:
go in interface Consumer
Throws:
java.lang.IllegalThreadStateException - if a subclass calls Thread.start() on the value of createThread()
DTraceException - if an exception occurs in the native DTrace library
See Also:
createThread()

stop

public void stop()
Description copied from interface: Consumer
Stops all tracing, as well as the background thread started by Consumer.go() to consume generated probe data. A stopped consumer cannot be restarted. It is necessary to close() a stopped consumer to release the system resources it holds.

A consumer may stop on its own in response to the exit() action (see exit() in the Special Actions section of the Actions and Subroutines chapter of the Solaris Dynamic Tracing Guide). Similarly, a consumer stops automatically if it has at least one target process and all its target processes have completed (see createProcess() and grabProcess()). A consumer also stops automatically if it encounters an exception while consuming probe data. In these cases it is not necessary to call stop(). If a consumer stops for any reason (an explicit call to stop() or any of the reasons just given), listeners are notified through the consumerStopped() method.

Note that a call to stop() blocks until the background thread started by go() actually stops. After stop() returns, a call to Consumer.isRunning() returns false. If a DTraceException is thrown while stopping this consumer, it is handled by the handler passed to Consumer.go(ExceptionHandler h) (or a default handler if none is specified).

Specified by:
stop in interface Consumer
Throws:
java.lang.IllegalThreadStateException - if attempting to stop() a running consumer while holding the lock on that consumer
See Also:
Consumer.go(), Consumer.abort(), Consumer.close()

abort

public void abort()
Description copied from interface: Consumer
Aborts the background thread started by Consumer.go(). abort() is effectively the same as Consumer.stop() except that it does not block (i.e. it does not wait until the background thread actually stops). Consumer.isRunning() is likely true immediately after a call to abort(), since an aborted consumer stops at a time specified as later. Specifically, a call to abort() stops tracing just before the next intervalBegan() event and stops consuming probe data by the subsequent intervalEnded() event. When the aborted consumer actually stops, listeners are notified in the consumerStopped() method, where it is convenient to Consumer.close() the stopped consumer after requesting the final aggregate.

The abort() and stop() methods have slightly different behavior when called just after go() but before the consumer actually starts running: It is possible to stop() a consumer before it starts running (resulting in a consumerStopped() event without a matching consumerStarted() event), whereas an aborted consumer will not stop until after it starts running, when it completes a single interval (that interval does not include sleeping to wait for traced probe data). Calling abort() before go() is legal and has the same effect as calling it after go() and before the consumer starts running. The last behavior follows from the design: You do not know the state of a consumer after calling abort(), nor is it necessary to know the state of a consumer before calling abort(). That may be preferable, for example, when you want to abort a consumer opened and started in another thread.

Specified by:
abort in interface Consumer
See Also:
Consumer.stop()

close

public void close()
Description copied from interface: Consumer
Closes an open consumer and releases the system resources it was holding. If the consumer is running, close() will Consumer.stop() it automatically. A closed consumer cannot be reopened. Closing a consumer that has not yet been opened makes it illegal to open that consumer afterwards. It is a no-op to call close() on a consumer that is already closed.

Specified by:
close in interface Consumer
Throws:
java.lang.IllegalThreadStateException - if attempting to close() a running consumer while holding the lock on that consumer
See Also:
Consumer.open(OpenFlag[] flags)

addConsumerListener

public void addConsumerListener(ConsumerListener l)
Description copied from interface: Consumer
Adds a listener for probe data generated by this consumer.

Specified by:
addConsumerListener in interface Consumer

removeConsumerListener

public void removeConsumerListener(ConsumerListener l)
Description copied from interface: Consumer
Removes a listener for probe data generated by this consumer.

Specified by:
removeConsumerListener in interface Consumer

getAggregate

public Aggregate getAggregate()
                       throws DTraceException
Description copied from interface: Consumer
Gets a snapshot of all aggregations except those that have already been captured in a PrintaRecord. Does not clear any aggregation.

Provides a programmatic alternative to the printa() action (see printa() in the Output Formatting chapter of the Solaris Dynamic Tracing Guide).

Specified by:
getAggregate in interface Consumer
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.getAggregate(Set includedAggregationNames, Set clearedAggregationNames)

getAggregate

public Aggregate getAggregate(java.util.Set<java.lang.String> includedAggregationNames)
                       throws DTraceException
Description copied from interface: Consumer
Gets a snapshot of all the specified aggregations except those that have already been captured in a PrintaRecord. Does not clear any aggregation.

Provides a programmatic alternative to the printa() action (see printa() in the Output Formatting chapter of the Solaris Dynamic Tracing Guide).

Specified by:
getAggregate in interface Consumer
Parameters:
includedAggregationNames - if null, all available aggregations are included; if non-null, only those aggregations specifically named by the given set are included
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.getAggregate(Set includedAggregationNames, Set clearedAggregationNames)

getAggregate

public Aggregate getAggregate(java.util.Set<java.lang.String> includedAggregationNames,
                              java.util.Set<java.lang.String> clearedAggregationNames)
                       throws DTraceException
Description copied from interface: Consumer
Gets a snapshot of all the specified aggregations except those that have already been captured in a PrintaRecord, with the side effect of atomically clearing any subset of those aggregations. Clearing an aggregation resets all of its values to zero without removing any of its keys. Leave aggregations uncleared to get running totals, otherwise specify that an aggregation be cleared to get values per time interval. Note that once an aggregation is captured in a PrintaRecord (as a result of the printa() action), it is no longer available to the getAggregate() method.

Provides a programmatic alternative to the printa() (see printa() in the Output Formatting chapter of the Solaris Dynamic Tracing Guide) and clear() actions.

Specified by:
getAggregate in interface Consumer
Parameters:
includedAggregationNames - if null, all available aggregations are included; if non-null, only those aggregations specifically named by the given set are included
clearedAggregationNames - if null, all available aggregations are cleared; if non-null, only those aggregations specifically named by the given set are cleared
Throws:
DTraceException - if an exception occurs in the native DTrace library

createProcess

public int createProcess(java.lang.String command)
                  throws DTraceException
Description copied from interface: Consumer
Creates a process by executing the given command on the system and returns the created process ID. The created process is suspended until calling Consumer.go() so that the process waits to do anything until this consumer has started tracing (allowing a process to be traced from the very beginning of its execution). The macro variable $target in a D program will be replaced by the process ID of the created process. When the created process exits, this consumer notifies listeners through the processStateChanged() method.

See the Target Process ID section of the Scripting chapter of the Solaris Dynamic Tracing Guide.

Specified by:
createProcess in interface Consumer
Parameters:
command - a string whose first token is assumed to be the name of the command and whose subsequent tokens are the arguments to that command.
Returns:
ID of the created process (pid)
Throws:
DTraceException - if the process cannot be created
See Also:
Consumer.grabProcess(int pid)

grabProcess

public void grabProcess(int pid)
                 throws DTraceException
Description copied from interface: Consumer
Grabs the specified process and caches its symbol tables. The macro variable $target in a D program will be replaced by the process ID of the grabbed process. When the specified process exits, this consumer notifies listeners through the processStateChanged() method.

See the Target Process ID section of the Scripting chapter of the Solaris Dynamic Tracing Guide.

Specified by:
grabProcess in interface Consumer
Parameters:
pid - process ID of the process to be grabbed
Throws:
DTraceException - if the process cannot be grabbed
See Also:
Consumer.createProcess(String command)

listProbes

public java.util.List<ProbeDescription> listProbes(ProbeDescription filter)
                                            throws DTraceException
Description copied from interface: Consumer
Lists probes that match the given probe description. See ProbeDescription for information about pattern syntax and wildcarding.

Specified by:
listProbes in interface Consumer
Parameters:
filter - use ProbeDescription.EMPTY to get all probes, otherwise get only those probes that match the given filter
Returns:
a non-null list of probe descriptions
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.open(OpenFlag[] flags), Consumer.close(), Consumer.listProbeDetail(ProbeDescription filter), Consumer.listProgramProbes(Program program)

listProbeDetail

public java.util.List<Probe> listProbeDetail(ProbeDescription filter)
                                      throws DTraceException
Description copied from interface: Consumer
Lists probes that match the given probe description and includes detail such as stability information about each listed probe.

Specified by:
listProbeDetail in interface Consumer
Parameters:
filter - use ProbeDescription.EMPTY to get all probes, otherwise get only those probes that match the given filter
Returns:
a non-null list of probe detail
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.listProbes(ProbeDescription filter), Consumer.listProgramProbeDetail(Program program)

listProgramProbes

public java.util.List<ProbeDescription> listProgramProbes(Program program)
                                                   throws DTraceException
Description copied from interface: Consumer
Lists probes that match the given compiled program. A probe matches a D program if that program contains any matching probe description.

Specified by:
listProgramProbes in interface Consumer
Parameters:
program - a Program identifier returned by compile(String program, ...) or compile(File program, ...)
Returns:
a non-null list of probe descriptions
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.listProbes(ProbeDescription filter)

listProgramProbeDetail

public java.util.List<Probe> listProgramProbeDetail(Program program)
                                             throws DTraceException
Description copied from interface: Consumer
Lists probes that match the given compiled program and includes detail such as stability information about each listed probe.

Specified by:
listProgramProbeDetail in interface Consumer
Parameters:
program - a Program identifier returned by compile(String program, ...) or compile(File program, ...)
Returns:
a non-null list of probe detail
Throws:
DTraceException - if an exception occurs in the native DTrace library
See Also:
Consumer.listProgramProbes(Program program), Consumer.listProbeDetail(ProbeDescription filter)

lookupKernelFunction

public java.lang.String lookupKernelFunction(int address)
Description copied from interface: Consumer
Gets the kernel function name for the given 32-bit kernel address.

Specified by:
lookupKernelFunction in interface Consumer
Parameters:
address - 32-bit kernel function address, such as the value of a Tuple member in an AggregationRecord to be converted for display
Returns:
the result of kernel function lookup as one of the following:
  • module`function
  • module`function+offset
  • module`address
  • address
where module and function are names, and offset and address are integers in hexadecimal format preceded by "0x". offset is the number of bytes from the beginning of the function, included when non-zero. address is simply the hex form of the input paramater, returned when function lookup fails. The exact details of this format are subject to change.
See Also:
Consumer.lookupKernelFunction(long address)

lookupKernelFunction

public java.lang.String lookupKernelFunction(long address)
Description copied from interface: Consumer
Gets the kernel function name for the given 64-bit kernel address.

Specified by:
lookupKernelFunction in interface Consumer
Parameters:
address - 64-bit kernel function address
Returns:
kernel function name
See Also:
Consumer.lookupKernelFunction(int address)

lookupUserFunction

public java.lang.String lookupUserFunction(int pid,
                                           int address)
Description copied from interface: Consumer
Gets the user function name for the given 32-bit user address and process ID.

Specified by:
lookupUserFunction in interface Consumer
Parameters:
pid - ID of the user process containing the addressed function
address - 32-bit user function address, such as the value of a Tuple member in an AggregationRecord to be converted for display.
Returns:
result of user function lookup as one of the following:
  • module`function
  • module`function+offset
  • module`address
  • address
where module and function are names, and offset and address are integers in hexadecimal format preceded by "0x". offset is the number of bytes from the beginning of the function, included when non-zero. address is simply the hex form of the input paramater, returned when function lookup fails. The exact details of this format are subject to change.
See Also:
Consumer.lookupUserFunction(int pid, long address)

lookupUserFunction

public java.lang.String lookupUserFunction(int pid,
                                           long address)
Description copied from interface: Consumer
Gets the user function name for the given 64-bit user address and process ID.

Specified by:
lookupUserFunction in interface Consumer
Parameters:
pid - ID of the user process containing the addressed function
address - 64-bit user function address
Returns:
user function name
See Also:
Consumer.lookupUserFunction(int pid, int address)

getVersion

public java.lang.String getVersion()
Description copied from interface: Consumer
Gets the version of the native DTrace library.

Specified by:
getVersion in interface Consumer
Returns:
version string generated by the native DTrace library (same as the output of dtrace(1M) with the -V option)

fireDataReceived

protected void fireDataReceived(DataEvent e)
                         throws ConsumerException
Throws:
ConsumerException

fireDataDropped

protected void fireDataDropped(DropEvent e)
                        throws ConsumerException
Throws:
ConsumerException

fireErrorEncountered

protected void fireErrorEncountered(ErrorEvent e)
                             throws ConsumerException
Throws:
ConsumerException

fireProcessStateChanged

protected void fireProcessStateChanged(ProcessEvent e)
                                throws ConsumerException
Throws:
ConsumerException

fireConsumerStarted

protected void fireConsumerStarted(ConsumerEvent e)

fireConsumerStopped

protected void fireConsumerStopped(ConsumerEvent e)

fireIntervalBegan

protected void fireIntervalBegan(ConsumerEvent e)

fireIntervalEnded

protected void fireIntervalEnded(ConsumerEvent e)

toString

public java.lang.String toString()
Gets a string representation of this consumer useful for logging and not intended for display. The exact details of the representation are unspecified and subject to change, but the following format may be regarded as typical:

 class-name[property1 = value1, property2 = value2]
 

Overrides:
toString in class java.lang.Object

finalize

protected void finalize()
Ensures that the close() method of this consumer has been called before it is garbage-collected. The intended safety net is weak because the JVM does not guarantee that an object will be garbage-collected when it is no longer referenced. Users of the API should call close() to ensure that all resources associated with this consumer are reclaimed in a timely manner.

Overrides:
finalize in class java.lang.Object
See Also:
close()