Mercurial > hg > graal-compiler

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java @ 20894:129a09815063

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: eclipseformat
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Fri, 10 Apr 2015 21:53:38 -0700
parents 263ab98b3bf0
children ca13a009e38b
comparison
equal deleted inserted replaced
20893:263ab98b3bf0 20894:129a09815063
67 * <p> 67 * <p>
68 * <h4>Options for creating listeners:</h4> 68 * <h4>Options for creating listeners:</h4>
69 * <p> 69 * <p>
70 * <ol> 70 * <ol>
71 * <li>Implement one of the <em>listener interfaces</em>: {@link SimpleInstrumentListener} or 71 * <li>Implement one of the <em>listener interfaces</em>: {@link SimpleInstrumentListener} or
72 * {@link StandardInstrumentListener} . Their event handling methods account for both the entry into an 72 * {@link StandardInstrumentListener} . Their event handling methods account for both the entry into
73 * AST node (about to call) and three possible kinds of <em>execution return</em> from an AST node.</li> 73 * an AST node (about to call) and three possible kinds of <em>execution return</em> from an AST
74 * node.</li>
74 * <li>Extend one of the <em>helper implementations</em>: {@link DefaultSimpleInstrumentListener} or 75 * <li>Extend one of the <em>helper implementations</em>: {@link DefaultSimpleInstrumentListener} or
75 * {@link DefaultStandardInstrumentListener}. These provide no-op implementation of every listener 76 * {@link DefaultStandardInstrumentListener}. These provide no-op implementation of every listener
76 * method, so only the methods of interest need to be overridden.</li> 77 * method, so only the methods of interest need to be overridden.</li>
77 * </ol> 78 * </ol>
78 * <p> 79 * <p>
83 * {@link StandardInstrumentListener} can interact directly with (and potentially affect) Truffle 84 * {@link StandardInstrumentListener} can interact directly with (and potentially affect) Truffle
84 * execution in general and Truffle optimization in particular. For example, it is possible to 85 * execution in general and Truffle optimization in particular. For example, it is possible to
85 * implement a debugger with this interface. 86 * implement a debugger with this interface.
86 * </p> 87 * </p>
87 * <p> 88 * <p>
88 * As a consequence, implementations of {@link StandardInstrumentListener} effectively become part of 89 * As a consequence, implementations of {@link StandardInstrumentListener} effectively become part
89 * the Truffle execution and must be coded according to general guidelines for Truffle 90 * of the Truffle execution and must be coded according to general guidelines for Truffle
90 * implementations. For example: 91 * implementations. For example:
91 * <ul> 92 * <ul>
92 * <li>Do not store {@link Frame} or {@link Node} references in fields.</li> 93 * <li>Do not store {@link Frame} or {@link Node} references in fields.</li>
93 * <li>Prefer {@code final} fields and (where performance is important) short methods.</li> 94 * <li>Prefer {@code final} fields and (where performance is important) short methods.</li>
94 * <li>If needed, pass along the {@link VirtualFrame} reference from an event notification as far as 95 * <li>If needed, pass along the {@link VirtualFrame} reference from an event notification as far as
108 * </ul> 109 * </ul>
109 * <p> 110 * <p>
110 * <h4>Allowing for AST cloning:</h4> 111 * <h4>Allowing for AST cloning:</h4>
111 * <p> 112 * <p>
112 * Truffle routinely <em>clones</em> ASTs, which has consequences for implementations of 113 * Truffle routinely <em>clones</em> ASTs, which has consequences for implementations of
113 * {@link StandardInstrumentListener} (but not for implementations of {@link SimpleInstrumentListener}, 114 * {@link StandardInstrumentListener} (but not for implementations of
114 * from which cloning is hidden). 115 * {@link SimpleInstrumentListener}, from which cloning is hidden).
115 * <ul> 116 * <ul>
116 * <li>Even though a {@link Probe} is uniquely associated with a particular location in the 117 * <li>Even though a {@link Probe} is uniquely associated with a particular location in the
117 * executing Guest Language program, execution events at that location will in general be 118 * executing Guest Language program, execution events at that location will in general be
118 * implemented by different {@link Node} instances, i.e. <em>clones</em> of the originally probed 119 * implemented by different {@link Node} instances, i.e. <em>clones</em> of the originally probed
119 * node.</li> 120 * node.</li>
179 180
180 /** 181 /**
181 * Creates an instrument that will route execution events to a listener, along with access to 182 * Creates an instrument that will route execution events to a listener, along with access to
182 * internal execution state. 183 * internal execution state.
183 * 184 *
184 * @param standardListener a listener for event generated by the instrument that provides access to 185 * @param standardListener a listener for event generated by the instrument that provides access
185 * internal execution state 186 * to internal execution state
186 * @param instrumentInfo optional description of the instrument's role, useful for debugging. 187 * @param instrumentInfo optional description of the instrument's role, useful for debugging.
187 * @return a new instrument, ready for attachment at a probe 188 * @return a new instrument, ready for attachment at a probe
188 */ 189 */
189 public static Instrument create(StandardInstrumentListener standardListener, String instrumentInfo) { 190 public static Instrument create(StandardInstrumentListener standardListener, String instrumentInfo) {
190 return new StandardInstrument(standardListener, instrumentInfo); 191 return new StandardInstrument(standardListener, instrumentInfo);