org.opensolaris.os.dtrace
Class UserStackRecord

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<UserStackRecord>, Record, StackValueRecord, ValueRecord

public final class UserStackRecord
extends java.lang.Object
implements StackValueRecord, java.io.Serializable, java.lang.Comparable<UserStackRecord>

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

Immutable. Supports persistence using XMLEncoder.

See Also:

Serialized Form

UserStackRecord

public UserStackRecord(int pid,
                       StackFrame[] frames,
                       byte[] rawBytes)

Creates a UserStackRecord with the given stack frames, user process ID, 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 UserStackRecord; may be null or empty to indicate that the raw stack data was not converted to human-readable stack frames (see StackValueRecord.getStackFrames())

pid - non-negative user process ID

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 UserStackRecord

Throws:

java.lang.NullPointerException - if the given array of raw bytes is null or if any element of the frames array is null

java.lang.IllegalArgumentException - if the given process ID is negative

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 include the process ID and are used in equals() and compareTo() to test equality and to determine the natural ordering of user 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()

getProcessID

public int getProcessID()

Gets the process ID associated with this record's user stack.

Returns:

non-negative pid

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

asKernelStackRecord

public KernelStackRecord asKernelStackRecord()

Gets a KernelStackRecord view of this record.

Returns:

non-null KernelStackRecord view of this record

equals

public boolean equals(java.lang.Object o)

Compares the specified object with this UserStackRecord for equality. Returns true if and only if the specified object is also a UserStackRecord and both stacks have the same raw stack data (including process ID).

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

Overrides:

equals in class java.lang.Object

Returns:

true if and only if the specified object is also a UserStackRecord and both stacks have the same raw stack data (including process ID)

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(UserStackRecord r)

Compares this record with the given UserStackRecord. 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 object is this UserStackRecord. If so, it returns 0.

Specified by:

compareTo in interface java.lang.Comparable<UserStackRecord>

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 the string representation of the view returned by asKernelStackRecord() preceded by the user process ID on its own line. The process ID is in the format process ID: pid (where pid is a decimal integer) and is indented by the same number of spaces as the stack frames. The exact format is subject to change.

Overrides:

toString in class java.lang.Object