Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.opensolaris.os.dtrace
Class LocalConsumer

    java.lang.Object
      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()`

Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD