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 package org.opensolaris.os.dtrace; 27 28 import java.util.*; 29 30 /** 31 * A value generated by the DTrace {@code stack()}, {@code ustack()}, or 32 * {@code jstack()} action. 33 * 34 * @author Tom Erickson 35 */ 36 public interface StackValueRecord extends ValueRecord { 37 /** 38 * Gets a copy of this record's stack frames, or an empty array if 39 * this record's raw stack data was not converted to human-readable 40 * stack frames by DTrace. Raw stack data is not converted (i.e. 41 * human-readable stack frames are omitted) whenever a {@code 42 * printa()} format string is specified without including the {@code 43 * %k} placeholder for the stack value represented by this record. 44 * (The {@code stack()}, {@code ustack()}, and {@code jstack()} 45 * actions are all usable as members of an aggregation tuple.) See 46 * the <a 47 * href=http://dtrace.org/guide/chp-fmt.html#chp-fmt-printa> 48 * <b>{@code printa()}</b></a> section of the <b>Output 49 * Formatting</b> chapter of the <i>Dynamic Tracing 50 * Guide</i> for details about {@code printa()} format strings. 51 * Human-readable stack frames are generated by default if {@code 52 * printa()} is called without specifying a format string, or when 53 * using {@link Consumer#getAggregate()} as an alternative to {@code 54 * printa()}. They are also generated when {@code stack()}, {@code 55 * ustack()}, or {@code jstack()} is used as a stand-alone action 56 * outside of an aggregation tuple. 57 * <p> 58 * The returned array is a copy and modifying it has no effect on 59 * this record. Elements of the returned array are not {@code 60 * null}. 61 * 62 * @return a non-null, possibly empty array of this record's 63 * human-readable stack frames, none of which are {@code null} 64 */ getStackFrames()65 public StackFrame[] getStackFrames(); 66 67 /** 68 * Gets the native DTrace representation of this record's stack as 69 * an array of raw bytes. The raw bytes are needed to distinguish 70 * stacks that have the same string representation but are 71 * considered distinct by DTrace. Duplicate stacks (stacks with the 72 * same human-readable stack frames) can have distinct raw stack 73 * data when program text is relocated. 74 * <p> 75 * Implementations of this interface use raw stack data to compute 76 * {@link Object#equals(Object o) equals()} and {@link 77 * Object#hashCode() hashCode()}. If the stack belongs to a user 78 * process, the raw bytes include the process ID. 79 * 80 * @return the native DTrace library's internal representation of 81 * this record's stack as a non-null array of bytes 82 */ getRawStackData()83 public byte[] getRawStackData(); 84 85 /** 86 * Gets the raw bytes used to represent this record's stack value in 87 * the native DTrace library. 88 * 89 * @return {@link #getRawStackData()} 90 */ getValue()91 public Object getValue(); 92 93 /** 94 * Gets a read-only {@code List} view of this record's stack frames. 95 * The returned list implements {@link java.util.RandomAccess}. It 96 * is empty if {@link #getStackFrames()} returns an empty array. 97 * 98 * @return non-null, unmodifiable {@code List} view of this record's 99 * stack frames 100 */ asList()101 public List <StackFrame> asList(); 102 } 103