StackValueRecord.java revision fb3fb4f3d76d55b64440afd0af72775dfad3bd1d
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License (the "License").
* You may not use this file except in compliance with the License.
*
* You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at usr/src/OPENSOLARIS.LICENSE.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information: Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*/
/*
* Copyright 2006 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*
* ident "%Z%%M% %I% %E% SMI"
*/
/**
* A value generated by the DTrace {@code stack()}, {@code ustack()}, or
* {@code jstack()} action.
*
* @author Tom Erickson
*/
public interface StackValueRecord extends ValueRecord {
/**
* 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 {@code
* printa()} format string is specified without including the {@code
* %k} placeholder for the stack value represented by this record.
* (The {@code stack()}, {@code ustack()}, and {@code jstack()}
* actions are all usable as members of an aggregation tuple.) See
* the <a
* <b>{@code printa()}</b></a> section of the <b>Output
* Formatting</b> chapter of the <i>Solaris Dynamic Tracing
* Guide</i> for details about {@code printa()} format strings.
* Human-readable stack frames are generated by default if {@code
* printa()} is called without specifying a format string, or when
* using {@link Consumer#getAggregate()} as an alternative to {@code
* printa()}. They are also generated when {@code stack()}, {@code
* ustack()}, or {@code jstack()} is used as a stand-alone action
* outside of an aggregation tuple.
* <p>
* The returned array is a copy and modifying it has no effect on
* this record. Elements of the returned array are not {@code
* null}.
*
* @return a non-null, possibly empty array of this record's
* human-readable stack frames, none of which are {@code null}
*/
public StackFrame[] getStackFrames();
/**
* 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.
* <p>
* Implementations of this interface use raw stack data to compute
* {@link Object#equals(Object o) equals()} and {@link
* Object#hashCode() hashCode()}. If the stack belongs to a user
* process, the raw bytes include the process ID.
*
* @return the native DTrace library's internal representation of
* this record's stack as a non-null array of bytes
*/
public byte[] getRawStackData();
/**
* Gets the raw bytes used to represent this record's stack value in
* the native DTrace library.
*
* @return {@link #getRawStackData()}
*/
/**
* Gets a read-only {@code List} view of this record's stack frames.
* The returned list implements {@link java.util.RandomAccess}. It
* is empty if {@link #getStackFrames()} returns an empty array.
*
* @return non-null, unmodifiable {@code List} view of this record's
* stack frames
*/
}