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 * Interface to the native DTrace library, each instance is a single
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace consumer. To consume the output of DTrace program actions,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@link #addConsumerListener(ConsumerListener l) register a probe data
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * listener}. To get a snapshot of all aggregations in a D program on
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * your own programmatic interval without relying on DTrace actions to
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * generate that output, use the {@link #getAggregate()} method.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see ProbeData
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see Aggregate
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @author Tom Erickson
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Optional flags passed to {@link #open(Consumer.OpenFlag[] flags)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Generate 32-bit D programs. {@code ILP32} and {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Consumer.OpenFlag#LP64 LP64} are mutually exclusive.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Generate 64-bit D programs. {@code LP64} and {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Consumer.OpenFlag#ILP32 ILP32} are mutually exclusive.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Opens this DTrace consumer. Optional flags indicate behaviors
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * that can only be set at the time of opening. Most optional
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * behaviors are set using {@link #setOption(String option, String
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * value) setOption()} after opening the consumer. In the great
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * majority of cases, the consumer is opened without specifying any
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <pre> {@code consumer.open();}</pre>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Subsequent calls to set options, compile DTrace programs, enable
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * probes, and run this consumer may be made from any thread.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if any of the given open flags is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalArgumentException if any of the given flags are
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * mutually exlusive
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if this consumer is closed or has
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * already been opened
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #compile(File program, String[] macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #compile(String program, String[] macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #enable()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #go()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void open(OpenFlag ... flags) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Compiles the given D program string. Optional macro arguments
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * replace corresponding numbered macro variables in the D program
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * starting at {@code $1}.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param program program string
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param macroArgs macro substitutions for <i>$n</i> placeholders
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * embedded in the given D program: {@code macroArgs[0]} replaces
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * all occurrences of {@code $1}, {@code macroArgs[1]} replaces all
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * occurrences of {@code $2}, and so on. {@code $0} is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * automatically replaced by the executable name and should not be
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * included in the {@code macroArgs} parameter. See the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidliq?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <b>Macro Arguments</b></a> section of the <b>Scripting</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * chapter of the <i>Solaris Dynamic Tracing Guide</i>.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return a non-null {@code Program} identifier that may be passed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * to {@link #enable(Program program) enable()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given program string or any
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * of the given macro arguments is {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(OpenFlag[] flags) open()} or after {@link #go()}, or if the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * consumer is closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #compile(File program, String[] macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public Program compile(String program, String ... macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Compiles the given D program file. Optional macro arguments
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * replace corresponding numbered macro variables in the D program
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * starting at {@code $1}.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param program program file
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param macroArgs macro substitutions for <i>$n</i> placeholders
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * embedded in the given D program: {@code macroArgs[0]} replaces
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * all occurrences of {@code $1}, {@code macroArgs[1]} replaces all
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * occurrences of {@code $2}, and so on. {@code $0} is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * automatically set to the name of the given file and should not be
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * included in the {@code macroArgs} parameter. See the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidliq?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <b>Macro Arguments</b></a> section of the <b>Scripting</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * chapter of the <i>Solaris Dynamic Tracing Guide</i>.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return a non-null {@code Program} identifier that may be passed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * to {@link #enable(Program program) enable()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given program file or any of
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the given macro arguments is {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(OpenFlag[] flags) open()} or after {@link #go()}, or if the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * consumer is closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws FileNotFoundException if the given program file cannot be
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IOException if an I/O error occurs while reading the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * contents of the given program file
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws SecurityException if a security manager exists and its
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@code checkRead()} method denies read access to the file
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #compile(String program, String[] macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public Program compile(File program, String ... macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee throws DTraceException, IOException, SecurityException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Enables all DTrace probes compiled by this consumer. Call {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * enable()} with no argument to enable everything this consumer has
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * compiled so far (most commonly a single program, the only one to
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * be compiled). Call with one {@link Program} at a time if you
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * need information about enabled probes specific to each program.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before compiling at least
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * one program, or if any compiled program is already enabled, or if
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@link #go()} was already called, or if this consumer is closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #enable(Program program)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Enables DTrace probes matching the given program and attaches
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * information about those probes to the given program. A probe
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * matched multiple times (within the same D program or in multiple
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * D programs) triggers the actions associated with each matching
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * occurrence every time that probe fires.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param program A {@code Program} identifier returned by {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #compile(String program, String[] macroArgs) compile(String
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * program, ...)} or {@link #compile(File program, String[]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * macroArgs) compile(File program, ...)}: If the given program is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@code null}, the call has the same behavior as {@link #enable()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * with no argument; if the given program is non-null, the call
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * enables only those probes matching that program. In the latter
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * case, the {@code Program} parameter is modified as a way of
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * passing back information about the given program and its matching
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * probes, including program stability.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalArgumentException if the given program is non-null
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * and not compiled by this {@code Consumer}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if the given program is already
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * enabled (or if the given program is {@code null} and <i>any</i>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * program is already enabled), or if {@link #go()} was already
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * called, or if this consumer is closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #compile(String program, String[] macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #compile(File program, String[] macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #enable()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #getProgramInfo(Program program)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void enable(Program program) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Attaches information about matching DTrace probes to the given
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * program. Attaches the same information to the given program as
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * that attached by {@link #enable(Program program)} but without
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * enabling the probes.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given program is {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalArgumentException if the given program was not
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * compiled by this {@code Consumer}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called after {@link #close()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #compile(String program, String[] macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #compile(File program, String[] macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #enable(Program program)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void getProgramInfo(Program program) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Sets a boolean option.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given option is {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if a value is expected for the given
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * option, or if the option is otherwise invalid
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the given option is a boolean compile-time option and {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #go()} has already been called (see {@link Option} for a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * breakdown of runtime and compile-time options)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #setOption(String option, String value)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #unsetOption(String option)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void setOption(String option) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Unsets a boolean option.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given option is {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if the given option is not a boolean
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * option, or if the option is otherwise invalid
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the given option is a boolean compile-time option and {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #go()} has already been called (see {@link Option} for a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * breakdown of runtime and compile-time options)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #setOption(String option)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void unsetOption(String option) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Sets the value of a DTrace option. If the given option affects
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * compile-time behavior, it must be set before calling {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #compile(String program, String[] macroArgs) compile(String
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * program, ...)} or {@link #compile(File program, String[]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * macroArgs) compile(File program, ...)} in order to have an effect
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * on compilation. Some runtime options including {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Option#switchrate switchrate} and {@link Option#aggrate aggrate}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * are settable while a consumer is running; others must be set
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * before calling {@link #go()}. See the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlis?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <b>Options and Tunables</b></a> chapter of the <i>Solaris Dynamic
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Guide</i> for information about specific options.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given option or value is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the given option is a boolean compile-time option and {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * go()} has already been called (see {@link Option} for a breakdown
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * of runtime and compile-time options)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException for any of the following:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <ul><li>The option is invalid</li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <li>The value is invalid for the given option</li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <li>{@code go()} has been called to start this consumer, and the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * option is not settable on a running consumer (some runtime
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * options, including {@link Option#switchrate switchrate} and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@link Option#aggrate aggrate} are settable while the consumer is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * running)</li></ul>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #open(OpenFlag[] flags)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #getOption(String option)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see Option
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void setOption(String option, String value) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets the value of a DTrace option.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given option is {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(OpenFlag[] flags) open()} or after {@link #close()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if the given option is invalid
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return the value of the given DTrace option: If the given option
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * is a boolean option and is currently unset, the returned value is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@link Option#UNSET}. If the given option is a <i>size</i>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * option, the returned value is in bytes. If the given option is a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <i>time</i> option, the returned value is in nanoseconds. If the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * given option is {@link Option#bufpolicy bufpolicy}, the returned
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * value is one of {@link Option#BUFPOLICY_RING BUFPOLICY_RING},
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@link Option#BUFPOLICY_FILL BUFPOLICY_FILL}, or {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Option#BUFPOLICY_SWITCH BUFPOLICY_SWITCH}. If the given option
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * is {@link Option#bufresize bufresize}, the returned value is one
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * of {@link Option#BUFRESIZE_AUTO BUFRESIZE_AUTO} or {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Option#BUFRESIZE_MANUAL BUFRESIZE_MANUAL}.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #setOption(String option)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #unsetOption(String option)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #setOption(String option, String value)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see Option
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public long getOption(String option) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Reports whether or not this consumer is open.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return {@code true} if and only if {@link #open(OpenFlag[]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * flags) open()} has been called on this consumer and {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #close()} has not
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Reports whether or not it is valid to call {@link #go()}.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return {@code true} if and only if at least one program has been
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * compiled, all compiled programs have been enabled, {@code go()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * has not already been called, and {@link #close()} has not been
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Reports whether or not this consumer is running. There may be a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * delay after calling {@link #go()} before this consumer actually
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * starts running (listeners are notified by the {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * ConsumerListener#consumerStarted(ConsumerEvent e)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * consumerStarted()} method).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return {@code true} if this consumer is running, {@code false}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * otherwise
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Reports whether or not this consumer is closed. A closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * consumer cannot be reopened.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Note that a closed consumer is different from a consumer that has
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * not yet been opened.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return {@code true} if {@link #close()} has been called on this
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * consumer, {@code false} otherwise
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Begin tracing and start a background thread to consume generated
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * probe data.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if not {@link #isEnabled()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #go(ExceptionHandler h)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #open(OpenFlag[] flags)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #compile(String program, String[] macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #compile(File program, String[] macroArgs)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #enable()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #stop()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #close()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Begin tracing and start a background thread to consume generated
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * probe data. Handle any exception thrown in the consumer thread
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * with the given handler.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if not {@link #isEnabled()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #go()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void go(ExceptionHandler h) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Stops all tracing, as well as the background thread started by
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@link #go()} to consume generated probe data. A stopped
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * consumer cannot be restarted. It is necessary to {@code close()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * a stopped consumer to release the system resources it holds.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * A consumer may stop on its own in response to the {@code exit()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * action (see <b>{@code exit()}</b> in the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhm?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <b>Special Actions</b></a> section of the <b>Actions and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Subroutines</b> chapter of the <i>Solaris Dynamic Tracing
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Guide</i>). Similarly, a consumer stops automatically if it has
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * at least one target process and all its target processes have
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * completed (see {@link #createProcess(String command)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * createProcess()} and {@link #grabProcess(int pid)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * grabProcess()}). A consumer also stops automatically if it
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * encounters an exception while consuming probe data. In these
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * cases it is not necessary to call {@code stop()}. If a consumer
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * stops for any reason (an explicit call to {@code stop()} or any
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * of the reasons just given), listeners are notified through the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@link ConsumerListener#consumerStopped(ConsumerEvent e)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * consumerStopped()} method.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Note that a call to {@code stop()} blocks until the background
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * thread started by {@code go()} actually stops. After {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * stop()} returns, a call to {@link #isRunning()} returns {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * false}. If a {@code DTraceException} is thrown while stopping
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * this consumer, it is handled by the handler passed to {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #go(ExceptionHandler h)} (or a default handler if none is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * specified).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link #go()} or
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * if {@code stop()} was already called
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #go()
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * @see #abort()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #close()
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * Aborts the background thread started by {@link #go()}. {@code
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * abort()} is effectively the same as {@link #stop()} except that
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * it does not block (i.e. it does not wait until the background
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * thread actually stops). {@link #isRunning()} is likely {@code
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * true} immediately after a call to {@code abort()}, since an
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * aborted consumer stops at a time specified as later.
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * Specifically, a call to {@code abort()} stops tracing just before
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * the next {@link ConsumerListener#intervalBegan(ConsumerEvent e)
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * intervalBegan()} event and stops consuming probe data by the
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * subsequent {@link ConsumerListener#intervalEnded(ConsumerEvent e)
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * intervalEnded()} event. When the aborted consumer actually
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * stops, listeners are notified in the {@link
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * ConsumerListener#consumerStopped(ConsumerEvent e)
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * consumerStopped()} method, where it is convenient to {@link
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * #close()} the stopped consumer after requesting the final
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * aggregate.
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * The {@code abort()} and {@code stop()} methods have slightly
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * different behavior when called <i>just after</i> {@code go()} but
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * <i>before</i> the consumer actually starts running: It is
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * possible to {@code stop()} a consumer before it starts running
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * (resulting in a {@code consumerStopped()} event without a
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * matching {@code consumerStarted()} event), whereas an aborted
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * consumer will not stop until after it starts running, when it
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * completes a single interval (that interval does not include
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * sleeping to wait for traced probe data). Calling {@code abort()}
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * before {@code go()} is legal and has the same effect as calling
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * it after {@code go()} and before the consumer starts running.
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * The last behavior follows from the design: You do not know the
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * state of a consumer after calling {@code abort()}, nor is it
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * necessary to know the state of a consumer before calling {@code
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * abort()}. That may be preferable, for example, when you want to
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * abort a consumer opened and started in another thread.
382dbd461c555f1c7e304a961fd0d4458d958ca2tomee * @see #stop()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Closes an open consumer and releases the system resources it was
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * holding. If the consumer is running, {@code close()} will {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #stop()} it automatically. A closed consumer cannot be
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * reopened. Closing a consumer that has not yet been opened makes
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * it illegal to open that consumer afterwards. It is a no-op to
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * call {@code close()} on a consumer that is already closed.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #open(OpenFlag[] flags)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Adds a listener for probe data generated by this consumer.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Removes a listener for probe data generated by this consumer.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void removeConsumerListener(ConsumerListener l);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets a snapshot of all aggregations except those that have
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * already been captured in a {@link PrintaRecord}. Does not clear
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * any aggregation.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Provides a programmatic alternative to the {@code printa(})
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * action (see <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhv?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <b>{@code printa()}</b></a> in the <b>Output Formatting</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * chapter of the <i>Solaris Dynamic Tracing Guide</i>).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link #go()} or
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * after {@link #close()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #getAggregate(Set includedAggregationNames, Set
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * clearedAggregationNames)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public Aggregate getAggregate() throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets a snapshot of all the specified aggregations except those
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * that have already been captured in a {@link PrintaRecord}. Does
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * not clear any aggregation.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Provides a programmatic alternative to the {@code printa(})
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * action (see <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhv?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <b>{@code printa()}</b></a> in the <b>Output Formatting</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * chapter of the <i>Solaris Dynamic Tracing Guide</i>).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param includedAggregationNames if {@code null}, all available
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * aggregations are included; if non-null, only those aggregations
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * specifically named by the given set are included
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link #go()} or
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * after {@link #close()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #getAggregate(Set includedAggregationNames, Set
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * clearedAggregationNames)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public Aggregate getAggregate(Set <String> includedAggregationNames)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets a snapshot of all the specified aggregations except those
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * that have already been captured in a {@link PrintaRecord}, with
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the side effect of atomically clearing any subset of those
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * aggregations. Clearing an aggregation resets all of its values
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * to zero without removing any of its keys. Leave aggregations
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * uncleared to get running totals, otherwise specify that an
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * aggregation be cleared to get values per time interval. Note
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * that once an aggregation is captured in a {@code PrintaRecord}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * (as a result of the {@code printa()} action), it is no longer
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * available to the {@code getAggregate()} method.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Provides a programmatic alternative to the {@code printa(}) (see
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhv?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <b>{@code printa()}</b></a> in the <b>Output Formatting</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * chapter of the <i>Solaris Dynamic Tracing Guide</i>) and {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * clear()} actions.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param includedAggregationNames if {@code null}, all available
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * aggregations are included; if non-null, only those aggregations
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * specifically named by the given set are included
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param clearedAggregationNames if {@code null}, all available
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * aggregations are cleared; if non-null, only those aggregations
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * specifically named by the given set are cleared
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link #go()} or
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * after {@link #close()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public Aggregate getAggregate(Set <String> includedAggregationNames,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Set <String> clearedAggregationNames) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Creates a process by executing the given command on the system
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * and returns the created process ID. The created process is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * suspended until calling {@link #go()} so that the process waits
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * to do anything until this consumer has started tracing (allowing
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * a process to be traced from the very beginning of its execution).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The macro variable {@code $target} in a D program will be
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * replaced by the process ID of the created process. When the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * created process exits, this consumer notifies listeners through
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the {@link ConsumerListener#processStateChanged(ProcessEvent e)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * processStateChanged()} method.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * See the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlir?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <b>Target Process ID</b></a> section of the <b>Scripting</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * chapter of the <i>Solaris Dynamic Tracing Guide</i>.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param command a string whose first token is assumed to be the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * name of the command and whose subsequent tokens are the arguments
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * to that command.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return ID of the created process (pid)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given command is {@code nul}l
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalArgumentException if the given command is empty or
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * contains only whitespace
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()},
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * or if the consumer is closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if the process cannot be created
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #grabProcess(int pid)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public int createProcess(String command) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Grabs the specified process and caches its symbol tables. The
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * macro variable {@code $target} in a D program will be replaced by
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the process ID of the grabbed process. When the specified
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * process exits, this consumer notifies listeners through the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@link ConsumerListener#processStateChanged(ProcessEvent e)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * processStateChanged()} method.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * See the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlir?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <b>Target Process ID</b></a> section of the <b>Scripting</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * chapter of the <i>Solaris Dynamic Tracing Guide</i>.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param pid process ID of the process to be grabbed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()},
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * or if the consumer is closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if the process cannot be grabbed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #createProcess(String command)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void grabProcess(int pid) throws DTraceException;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Lists probes that match the given probe description. See {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * ProbeDescription} for information about pattern syntax and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * wildcarding.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param filter use {@link ProbeDescription#EMPTY} to get all
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * probes, otherwise get only those probes that match the given
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return a non-null list of probe descriptions
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()},
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * or if the consumer is closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #open(OpenFlag[] flags)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #close()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #listProbeDetail(ProbeDescription filter)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #listProgramProbes(Program program)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public List <ProbeDescription> listProbes(ProbeDescription filter)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Lists probes that match the given probe description and includes
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * detail such as stability information about each listed probe.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param filter use {@link ProbeDescription#EMPTY} to get all
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * probes, otherwise get only those probes that match the given
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return a non-null list of probe detail
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()},
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * or if the consumer is closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #listProbes(ProbeDescription filter)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #listProgramProbeDetail(Program program)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public List <Probe> listProbeDetail(ProbeDescription filter)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Lists probes that match the given compiled program. A probe
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * matches a D program if that program contains any matching probe
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * description.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param program a {@code Program} identifier returned by {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #compile(String program, String[] macroArgs) compile(String
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * program, ...)} or {@link #compile(File program, String[]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * macroArgs) compile(File program, ...)}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return a non-null list of probe descriptions
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given program identifier is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalArgumentException if the specified program was not
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * compiled by this consumer
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()},
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * or if the consumer is closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #listProbes(ProbeDescription filter)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public List <ProbeDescription> listProgramProbes(Program program)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Lists probes that match the given compiled program and includes
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * detail such as stability information about each listed probe.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param program a {@code Program} identifier returned by {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #compile(String program, String[] macroArgs) compile(String
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * program, ...)} or {@link #compile(File program, String[]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * macroArgs) compile(File program, ...)}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return a non-null list of probe detail
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given program identifier is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalArgumentException if the specified program was not
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * compiled by this consumer
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()},
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * or if the consumer is closed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws DTraceException if an exception occurs in the native
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #listProgramProbes(Program program)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #listProbeDetail(ProbeDescription filter)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public List <Probe> listProgramProbeDetail(Program program)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets the kernel function name for the given 32-bit kernel
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param address 32-bit kernel function address, such as the value
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * of a {@link Tuple} member in an {@link AggregationRecord} to be
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * converted for display
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return the result of kernel function lookup as one of the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * following:<ul><li>{@code module`function}</li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <li>{@code module`function+offset}</li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <li>{@code module`address}</li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <li>{@code address}</li></ul> where {@code module} and {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * function} are names, and {@code offset} and {@code address} are
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * integers in hexadecimal format preceded by "{@code 0x}". {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * offset} is the number of bytes from the beginning of the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * function, included when non-zero. {@code address} is simply the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * hex form of the input paramater, returned when function lookup
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * fails. The exact details of this format are subject to change.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link #go()} or
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * after {@link #close()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #lookupKernelFunction(long address)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets the kernel function name for the given 64-bit kernel
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param address 64-bit kernel function address
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return kernel function name
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link #go()} or
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * after {@link #close()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #lookupKernelFunction(int address)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets the user function name for the given 32-bit user address and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * process ID.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param pid ID of the user process containing the addressed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param address 32-bit user function address, such as the value
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * of a {@link Tuple} member in an {@link AggregationRecord} to be
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * converted for display.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return result of user function lookup as one of the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * following:<ul> <li>{@code module`function}</li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <li>{@code module`function+offset}</li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <li>{@code module`address}</li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <li>{@code address}</li></ul> where {@code module} and {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * function} are names, and {@code offset} and {@code address} are
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * integers in hexadecimal format preceded by "{@code 0x}". {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * offset} is the number of bytes from the beginning of the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * function, included when non-zero. {@code address} is simply the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * hex form of the input paramater, returned when function lookup
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * fails. The exact details of this format are subject to change.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link #go()} or
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * after {@link #close()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #lookupUserFunction(int pid, long address)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public String lookupUserFunction(int pid, int address);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets the user function name for the given 64-bit user address and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * process ID.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param pid ID of the user process containing the addressed
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param address 64-bit user function address
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return user function name
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalStateException if called before {@link #go()} or
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * after {@link #close()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see #lookupUserFunction(int pid, int address)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public String lookupUserFunction(int pid, long address);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets the version of the native DTrace library.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return version string generated by the native DTrace library
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * (same as the output of {@code dtrace(1M)} with the {@code -V}