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 ProbeData

    java.lang.Object
      org.opensolaris.os.dtrace.ProbeData

All Implemented Interfaces:
  java.io.Serializable, java.lang.Comparable<ProbeData>

    public final class ProbeData

extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<ProbeData>

Data generated when a DTrace probe fires, contains one record for every record-generating action in the probe. (Some D actions, such as `clear()`, do not generate a `ProbeData` record.) A `Consumer` gets data from DTrace by registering a `listener` to get probe data whenever a probe fires:

         Consumer consumer = new LocalConsumer();
         consumer.addConsumerListener(new ConsumerAdapter() {
             public void dataReceived(DataEvent e) {
                 ProbeData probeData = e.getProbeData();
                 System.out.println(probeData);
             }
         });

Getting DTrace to generate that probe data involves compiling, enabling, and running a D program:

         try {
             consumer.open();
             consumer.compile(program);
             consumer.enable(); // instruments code at matching probe points
             consumer.go(); // non-blocking; generates probe data in background
         } catch (DTraceException e) {
             e.printStackTrace();
         }

Currently the `ProbeData` instance does not record a timestamp. If you need a timestamp, trace the built-in `timestamp` variable in your D program. (See the Built-in Variables section of the Variables chapter of the Solaris Dynamic Tracing Guide).

Immutable. Supports persistence using `XMLEncoder`.

See Also:
  `Consumer.addConsumerListener(ConsumerListener l)`, `ConsumerListener.dataReceived(DataEvent e)`, Serialized Form

Nested Class Summary
`static class` | `ProbeData.KeyField` Enumerates the fields by which `ProbeData` may be sorted using the `getComparator()` convenience method.

Constructor Summary
`ProbeData(int enabledProbeID, int cpuID, ProbeDescription p, Flow f, java.util.List<Record> recordList)` Creates a probe data instance with the given properties and list of records.

Method Summary
`int` | `compareTo(ProbeData d)` Natural ordering of probe data.
`static java.util.Comparator<ProbeData>` | `getComparator(ProbeData.KeyField... f)` Convenience method, gets a comparator that sorts multiple `ProbeDescription` instances by the specified field or fields.
`int` | `getCPU()` Gets the ID of the CPU on which the probe fired.
`ProbeDescription` | `getEnabledProbeDescription()` Gets the enabled probe description.
`int` | `getEnabledProbeID()` Gets the enabled probe ID.
`Flow` | `getFlow()` Gets the current state of control flow (function entry or return, and depth in call stack) at the time of the probe firing that generated this `ProbeData` instance, or `null` if such information was not requested with the `flowindent` option.
`java.util.List<Record>` | `getRecords()` Gets the records generated by the actions of the probe that fired, in the same order as the actions that generated the records.
`java.lang.String` | `toString()` Gets a string representation of this `ProbeData` instance useful for logging and not intended for display.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### ProbeData

    public ProbeData(int enabledProbeID,
                     int cpuID,
                     ProbeDescription p,
                     Flow f,
                     java.util.List<Record> recordList)

  Creates a probe data instance with the given properties and list of records. Supports XML persistence.

  Parameters:
    `enabledProbeID` - identifies the enabled probe that fired; the ID is generated by the native DTrace library to distinguish all probes enabled by the source consumer (as opposed to all probes on the system)
    `cpuID` - non-negative ID, identifies the CPU on which the probe fired
    `p` - identifies the enabled probe that fired
    `f` - current state of control flow (entry or return and depth in call stack) at time of probe firing, included if `flowindent` option used, `null` otherwise
    `recordList` - list of records generated by D actions in the probe that fired, one record per action, may be empty
  Throws:
    `java.lang.NullPointerException` - if the given probe description or list of records is `null`

Method Detail

### getComparator

    public static java.util.Comparator<ProbeData> getComparator(ProbeData.KeyField... f)

  Convenience method, gets a comparator that sorts multiple `ProbeDescription` instances by the specified field or fields. If more than one sort field is specified, the probe data are sorted by the first field, and in case of a tie, by the second field, and so on, in the order that the fields are specified.

  Parameters:
    `f` - field specifiers given in descending order of sort priority; lower priority fields are only compared (as a tie breaker) when all higher priority fields are equal
  Returns:
    non-null probe data comparator that sorts by the specified sort fields in the given order

### getEnabledProbeID

    public int getEnabledProbeID()

  Gets the enabled probe ID. Identifies the enabled probe that fired and generated this `ProbeData`. The "epid" is different from `ProbeDescription.getID()` in that it identifies a probe among all probes enabled by the source `Consumer`, rather than among all the probes on the system.

  Returns:
    the enabled probe ID generated by the native DTrace library

### getCPU

    public int getCPU()

  Gets the ID of the CPU on which the probe fired.

  Returns:
    ID of the CPU on which the probe fired

### getEnabledProbeDescription

    public ProbeDescription getEnabledProbeDescription()

  Gets the enabled probe description. Identifies the enabled probe that fired and generated this `ProbeData`.

  Returns:
    non-null probe description

### getFlow

    public Flow getFlow()

  Gets the current state of control flow (function entry or return, and depth in call stack) at the time of the probe firing that generated this `ProbeData` instance, or `null` if such information was not requested with the `flowindent` option.

  Returns:
    a description of control flow across function boundaries, or `null` if `Consumer.getOption(Option.flowindent)` returns `Option.UNSET`
  See Also:
    `Consumer.setOption(String option)`, `Option.flowindent`

### getRecords

    public java.util.List<Record> getRecords()

  Gets the records generated by the actions of the probe that fired, in the same order as the actions that generated the records. The returned list includes one record for every record-generating D action (some D actions, such as `clear()`, do not generate records).

  Returns:
    non-null, unmodifiable list view of the records belonging to this `ProbeData` in the order of the actions in the DTrace probe that generated them (record-producing actions are generally those that produce output, such as `printf()`, but also the `exit()` action)

### compareTo

    public int compareTo(ProbeData d)

  Natural ordering of probe data. Sorts probe data by records first, then if record data is equal, by enabled probe ID.

  Specified by:
    `compareTo` in interface `java.lang.Comparable<ProbeData>`
  Parameters:
    `d` - probe data to be compared with this probe data
  Returns:
    a negative number, zero, or a positive number as this probe data is less than, equal to, or greater than the given probe data
  Throws:
    `java.lang.NullPointerException` - if the given probe data is `null`
    `java.lang.ClassCastException` - if record lists of both `ProbeData` instances are not mutually comparable because corresponding list elements are not comparable or the lists themselves are different lengths
  See Also:
    `getComparator(KeyField[] f)`

### toString

    public java.lang.String toString()

  Gets a string representation of this `ProbeData` instance 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`

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