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