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

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

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