org.opensolaris.os.dtrace
Interface StackValueRecord

All Superinterfaces:
Record, ValueRecord
All Known Implementing Classes:
KernelStackRecord, UserStackRecord

public interface StackValueRecord
extends ValueRecord

A value generated by the DTrace stack(), ustack(), or jstack() action.


Method Summary
 java.util.List<StackFrame> asList()
          Gets a read-only List view of this record's stack frames.
 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.
 

Method Detail

getStackFrames

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. 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.

Returns:
a non-null, possibly empty array of this record's human-readable stack frames, none of which are null

getRawStackData

byte[] getRawStackData()
Gets the native DTrace representation of this record's stack as an array of raw bytes. The raw bytes are needed to distinguish stacks that have the same string representation but are considered distinct by DTrace. Duplicate stacks (stacks with the same human-readable stack frames) can have distinct raw stack data when program text is relocated.

Implementations of this interface use raw stack data to compute equals() and hashCode(). If the stack belongs to a user process, the raw bytes include the process ID.

Returns:
the native DTrace library's internal representation of this record's stack as a non-null array of bytes

getValue

java.lang.Object getValue()
Gets the raw bytes used to represent this record's stack value in the native DTrace library.

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

asList

java.util.List<StackFrame> asList()
Gets a read-only List view of this record's stack frames. The returned list implements RandomAccess. It is empty if getStackFrames() returns an empty array.

Returns:
non-null, unmodifiable List view of this record's stack frames