os/dtrace/Consumer.java

35  * DTrace consumer.  To consume the output of DTrace program actions,
37  * listener}.  To get a snapshot of all aggregations in a D program on
84      * @see #compile(File program, String[] macroArgs)
85      * @see #compile(String program, String[] macroArgs)
92      * Compiles the given D program string.  Optional macro arguments
93      * replace corresponding numbered macro variables in the D program
96      * @param program program string
98      * embedded in the given D program: {@code macroArgs[0]} replaces
107      * to {@link #enable(Program program) enable()}
108      * @throws NullPointerException if the given program string or any
115      * @see #compile(File program, String[] macroArgs)
117     public Program compile(String program, String ... macroArgs)
121      * Compiles the given D program file.  Optional macro arguments
122      * replace corresponding numbered macro variables in the D program
125      * @param program program file
127      * embedded in the given D program: {@code macroArgs[0]} replaces
136      * to {@link #enable(Program program) enable()}
137      * @throws NullPointerException if the given program file or any of
144      * @throws FileNotFoundException if the given program file cannot be
147      * contents of the given program file
150      * @see #compile(String program, String[] macroArgs)
152     public Program compile(File program, String ... macroArgs)
158      * compiled so far (most commonly a single program, the only one to
160      * need information about enabled probes specific to each program.
163      * one program, or if any compiled program is already enabled, or if
167      * @see #enable(Program program)
172      * Enables DTrace probes matching the given program and attaches
173      * information about those probes to the given program.  A probe
174      * matched multiple times (within the same D program or in multiple
178      * @param program  A {@code Program} identifier returned by {@link
179      * #compile(String program, String[] macroArgs) compile(String
180      * program, ...)} or {@link #compile(File program, String[]
181      * macroArgs) compile(File program, ...)}:  If the given program is
183      * with no argument; if the given program is non-null, the call
184      * enables only those probes matching that program.  In the latter
186      * passing back information about the given program and its matching
187      * probes, including program stability.
188      * @throws IllegalArgumentException if the given program is non-null
190      * @throws IllegalStateException if the given program is already
191      * enabled (or if the given program is {@code null} and <i>any</i>
192      * program is already enabled), or if {@link #go()} was already
196      * @see #compile(String program, String[] macroArgs)
197      * @see #compile(File program, String[] macroArgs)
199      * @see #getProgramInfo(Program program)
201     public void enable(Program program) throws DTraceException;
205      * program.  Attaches the same information to the given program as
206      * that attached by {@link #enable(Program program)} but without
209      * @throws NullPointerException if the given program is {@code null}
210      * @throws IllegalArgumentException if the given program was not
215      * @see #compile(String program, String[] macroArgs)
216      * @see #compile(File program, String[] macroArgs)
217      * @see #enable(Program program)
219     public void getProgramInfo(Program program) throws DTraceException;
255      * #compile(String program, String[] macroArgs) compile(String
256      * program, ...)} or {@link #compile(File program, String[]
257      * macroArgs) compile(File program, ...)} in order to have an effect
327      * @return {@code true} if and only if at least one program has been
367      * @see #compile(String program, String[] macroArgs)
368      * @see #compile(File program, String[] macroArgs)
570      * The macro variable {@code $target} in a D program will be
598      * macro variable {@code $target} in a D program will be replaced by
635      * @see #listProgramProbes(Program program)
654      * @see #listProgramProbeDetail(Program program)
660      * Lists probes that match the given compiled program.  A probe
661      * matches a D program if that program contains any matching probe
664      * @param program  a {@code Program} identifier returned by {@link
665      * #compile(String program, String[] macroArgs) compile(String
666      * program, ...)} or {@link #compile(File program, String[]
667      * macroArgs) compile(File program, ...)}
669      * @throws NullPointerException if the given program identifier is
671      * @throws IllegalArgumentException if the specified program was not
680     public List <ProbeDescription> listProgramProbes(Program program)
684      * Lists probes that match the given compiled program and includes
687      * @param program  a {@code Program} identifier returned by {@link
688      * #compile(String program, String[] macroArgs) compile(String
689      * program, ...)} or {@link #compile(File program, String[]
690      * macroArgs) compile(File program, ...)}
692      * @throws NullPointerException if the given program identifier is
694      * @throws IllegalArgumentException if the specified program was not
701      * @see #listProgramProbes(Program program)
704     public List <Probe> listProgramProbeDetail(Program program)