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 KernelStackRecord

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

All Implemented Interfaces:
  java.io.Serializable, java.lang.Comparable<KernelStackRecord>, Record, StackValueRecord, ValueRecord

    public final class KernelStackRecord

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

A value generated by the DTrace `stack()` action.

Immutable. Supports persistence using `XMLEncoder`.

See Also:
  Serialized Form

Constructor Summary
`KernelStackRecord(StackFrame[] frames, byte[] rawBytes)` Creates a `KernelStackRecord` with the given stack frames and raw stack data.

Method Summary
`java.util.List<StackFrame>` | `asList()` Gets a read-only `List` view of this record's stack frames.
`int` | `compareTo(KernelStackRecord r)` Compares this record with the given `KernelStackRecord`.
`boolean` | `equals(java.lang.Object o)` Compares the specified object with this `KernelStackRecord` for equality.
`byte[]` | `getRawStackData()` Gets the native DTrace representation of this record's stack as an array of raw bytes.
`StackFrame[]` | `getStackFrames()` Gets a copy of this record's stack frames, or an empty array if this record's raw stack data was not converted to human-readable stack frames by DTrace.
`java.lang.Object` | `getValue()` Gets the raw bytes used to represent this record's stack value in the native DTrace library.
`int` | `hashCode()` Overridden to ensure that equal instances have equal hash codes.
`java.lang.String` | `toString()` Gets a multi-line string representation of a stack with one frame per line.

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

Constructor Detail

### KernelStackRecord

    public KernelStackRecord(StackFrame[] frames,
                             byte[] rawBytes)

  Creates a `KernelStackRecord` with the given stack frames and raw stack data. Supports XML persistence.

  Parameters:
    `frames` - array of human-readable stack frames, copied so that later modifying the given frames array will not affect this `KernelStackRecord`; may be `null` or empty to indicate that the raw stack data was not converted to human-readable stack frames (see `StackValueRecord.getStackFrames()`)
    `rawBytes` - array of raw bytes used to represent this stack value in the native DTrace library, needed to distinguish stacks that have the same display value but are considered distinct by DTrace; copied so that later modifying the given array will not affect this `KernelStackRecord`
  Throws:
    `java.lang.NullPointerException` - if the given array of raw bytes is `null` or if any element of the `frames` array is `null`

Method Detail

### getStackFrames

    public StackFrame[] getStackFrames()

  Description copied from interface: `StackValueRecord`
  Gets a copy of this record's stack frames, or an empty array if this record's raw stack data was not converted to human-readable stack frames by DTrace. Raw stack data is not converted (i.e. human-readable stack frames are omitted) whenever a `printa()` format string is specified without including the `%k` placeholder for the stack value represented by this record. (The `stack()`, `ustack()`, and `jstack()` actions are all usable as members of an aggregation tuple.) See the `printa()` section of the Output Formatting chapter of the Solaris Dynamic Tracing Guide for details about `printa()` format strings. Human-readable stack frames are generated by default if `printa()` is called without specifying a format string, or when using `Consumer.getAggregate()` as an alternative to `printa()`. They are also generated when `stack()`, `ustack()`, or `jstack()` is used as a stand-alone action outside of an aggregation tuple.

  The returned array is a copy and modifying it has no effect on this record. Elements of the returned array are not `null`.

  Specified by:
    `getStackFrames` in interface `StackValueRecord`
  Returns:
    a non-null, possibly empty array of this record's human-readable stack frames, none of which are `null`

### getRawStackData

    public byte[] getRawStackData()

  Gets the native DTrace representation of this record's stack as an array of raw bytes. The raw bytes are used in `equals()` and `compareTo()` to test equality and to determine the natural ordering of kernel stack records.

  Specified by:
    `getRawStackData` in interface `StackValueRecord`
  Returns:
    the native DTrace library's internal representation of this record's stack as a non-null array of bytes

### getValue

    public java.lang.Object getValue()

  Gets the raw bytes used to represent this record's stack value in the native DTrace library. To get a human-readable representation, call `toString()`.

  Specified by:
    `getValue` in interface `StackValueRecord`
  Specified by:
    `getValue` in interface `ValueRecord`
  Returns:
    `getRawStackData()`

### asList

    public java.util.List<StackFrame> asList()

  Description copied from interface: `StackValueRecord`
  Gets a read-only `List` view of this record's stack frames. The returned list implements `RandomAccess`. It is empty if `StackValueRecord.getStackFrames()` returns an empty array.

  Specified by:
    `asList` in interface `StackValueRecord`
  Returns:
    non-null, unmodifiable `List` view of this record's stack frames

### equals

    public boolean equals(java.lang.Object o)

  Compares the specified object with this `KernelStackRecord` for equality. Returns `true` if and only if the specified object is also a `KernelStackRecord` and both records have the same raw stack data.

  This implementation first checks if the specified object is this `KernelStackRecord`. If so, it returns `true`.

  Overrides:
    `equals` in class `java.lang.Object`
  Returns:
    `true` if and only if the specified object is also a `KernelStackRecord` and both records have the same raw stack data

### hashCode

    public int hashCode()

  Overridden to ensure that equal instances have equal hash codes.

  Overrides:
    `hashCode` in class `java.lang.Object`

### compareTo

    public int compareTo(KernelStackRecord r)

  Compares this record with the given `KernelStackRecord`. Compares the first unequal pair of bytes at the same index in each record's raw stack data, or if all corresponding bytes are equal, compares the length of each record's array of raw stack data. Corresponding bytes are compared as unsigned values. The `compareTo()` method is compatible with `equals()`.

  This implementation first checks if the specified record is this `KernelStackRecord`. If so, it returns `0`.

  Specified by:
    `compareTo` in interface `java.lang.Comparable<KernelStackRecord>`
  Returns:
    -1, 0, or 1 as this record's raw stack data is less than, equal to, or greater than the given record's raw stack data.

### toString

    public java.lang.String toString()

  Gets a multi-line string representation of a stack with one frame per line. Each line is of the format `module`function+offset`, where `module` and `function` are symbol names and offset is a hex integer preceded by `0x`. For example: `genunix`open+0x19`. The offset (and the preceding '+' sign) are omitted if offset is zero. If function name lookup fails, the raw pointer value is used instead. In that case, the module name (and the ` delimiter) may or may not be present, depending on whether or not module lookup also fails, and a raw pointer value appears in place of `function+offset` as a hex value preceded by `0x`. The format just described, not including surrounding whitespce, is defined in the native DTrace library and is as stable as that library definition. Each line is indented by an equal (unspecified) number of spaces.

  If human-readable stack frames are not available (see `getStackFrames()`), a table represenation of `getRawStackData()` is returned instead. The table displays 16 bytes per row in unsigned hex followed by the ASCII character representations of those bytes. Each unprintable character is represented by a period (.).

  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