1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21 22 /* 23 * Copyright 2006 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 * 26 * ident "%Z%%M% %I% %E% SMI" 27 */ 28 package org.opensolaris.os.dtrace; 29 30 import java.util.*; 31 32 /** 33 * A value generated by the DTrace {@code stack()}, {@code ustack()}, or 34 * {@code jstack()} action. 35 * 36 * @author Tom Erickson 37 */ 38 public interface StackValueRecord extends ValueRecord { 39 /** 40 * Gets a copy of this record's stack frames, or an empty array if 41 * this record's raw stack data was not converted to human-readable 42 * stack frames by DTrace. Raw stack data is not converted (i.e. 43 * human-readable stack frames are omitted) whenever a {@code 44 * printa()} format string is specified without including the {@code 45 * %k} placeholder for the stack value represented by this record. 46 * (The {@code stack()}, {@code ustack()}, and {@code jstack()} 47 * actions are all usable as members of an aggregation tuple.) See 48 * the <a 49 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidli3?a=view> 50 * <b>{@code printa()}</b></a> section of the <b>Output 51 * Formatting</b> chapter of the <i>Solaris Dynamic Tracing 52 * Guide</i> for details about {@code printa()} format strings. 53 * Human-readable stack frames are generated by default if {@code 54 * printa()} is called without specifying a format string, or when 55 * using {@link Consumer#getAggregate()} as an alternative to {@code 56 * printa()}. They are also generated when {@code stack()}, {@code 57 * ustack()}, or {@code jstack()} is used as a stand-alone action 58 * outside of an aggregation tuple. 59 * <p> 60 * The returned array is a copy and modifying it has no effect on 61 * this record. Elements of the returned array are not {@code 62 * null}. 63 * 64 * @return a non-null, possibly empty array of this record's 65 * human-readable stack frames, none of which are {@code null} 66 */ 67 public StackFrame[] getStackFrames(); 68 69 /** 70 * Gets the native DTrace representation of this record's stack as 71 * an array of raw bytes. The raw bytes are needed to distinguish 72 * stacks that have the same string representation but are 73 * considered distinct by DTrace. Duplicate stacks (stacks with the 74 * same human-readable stack frames) can have distinct raw stack 75 * data when program text is relocated. 76 * <p> 77 * Implementations of this interface use raw stack data to compute 78 * {@link Object#equals(Object o) equals()} and {@link 79 * Object#hashCode() hashCode()}. If the stack belongs to a user 80 * process, the raw bytes include the process ID. 81 * 82 * @return the native DTrace library's internal representation of 83 * this record's stack as a non-null array of bytes 84 */ 85 public byte[] getRawStackData(); 86 87 /** 88 * Gets the raw bytes used to represent this record's stack value in 89 * the native DTrace library. 90 * 91 * @return {@link #getRawStackData()} 92 */ 93 public Object getValue(); 94 95 /** 96 * Gets a read-only {@code List} view of this record's stack frames. 97 * The returned list implements {@link java.util.RandomAccess}. It 98 * is empty if {@link #getStackFrames()} returns an empty array. 99 * 100 * @return non-null, unmodifiable {@code List} view of this record's 101 * stack frames 102 */ 103 public List <StackFrame> asList(); 104 } 105