Mercurial > hg > truffle

comparison truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/TruffleLanguage.java @ 22214:3aad794eec0e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: first large merge of instrumentation code into the TruffleVM framework - introduce the Instrumenter class, held by the TruffleVM to support instrumentation services - reimplement Probe-realated services (formerly statics in Probe.java) to be provided by the Instrumenter- add new Accessors - change the TruffleVM startup sequence - change the APIs of the Debugger and many other classes
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 14 Sep 2015 22:59:51 -0700
parents c334865b9d42
children d3bdaa91bc82
comparison
equal deleted inserted replaced
22136:1d804d691dc7 22214:3aad794eec0e
22 * or visit www.oracle.com if you need additional information or have any 22 * or visit www.oracle.com if you need additional information or have any
23 * questions. 23 * questions.
24 */ 24 */
25 package com.oracle.truffle.api; 25 package com.oracle.truffle.api;
26 26
27 import com.oracle.truffle.api.debug.*; 27 import java.io.IOException;
28 import com.oracle.truffle.api.impl.*; 28 import java.io.Reader;
29 import com.oracle.truffle.api.instrument.*; 29 import java.io.Writer;
30 import com.oracle.truffle.api.nodes.Node; 30 import java.lang.annotation.ElementType;
31 import com.oracle.truffle.api.source.*; 31 import java.lang.annotation.Retention;
32 import java.io.*; 32 import java.lang.annotation.RetentionPolicy;
33 import java.lang.annotation.*; 33 import java.lang.annotation.Target;
34 import java.util.Collections; 34 import java.util.Collections;
35 import java.util.List;
35 import java.util.Map; 36 import java.util.Map;
36 import java.util.WeakHashMap; 37 import java.util.WeakHashMap;
38
39 import com.oracle.truffle.api.debug.DebugSupportProvider;
40 import com.oracle.truffle.api.frame.MaterializedFrame;
41 import com.oracle.truffle.api.impl.Accessor;
42 import com.oracle.truffle.api.impl.FindContextNode;
43 import com.oracle.truffle.api.instrument.ASTProber;
44 import com.oracle.truffle.api.instrument.AdvancedInstrumentResultListener;
45 import com.oracle.truffle.api.instrument.AdvancedInstrumentRoot;
46 import com.oracle.truffle.api.instrument.AdvancedInstrumentRootFactory;
47 import com.oracle.truffle.api.instrument.Instrument;
48 import com.oracle.truffle.api.instrument.ToolSupportProvider;
49 import com.oracle.truffle.api.instrument.Visualizer;
50 import com.oracle.truffle.api.nodes.Node;
51 import com.oracle.truffle.api.source.Source;
37 52
38 /** 53 /**
39 * An entry point for everyone who wants to implement a Truffle based language. By providing an 54 * An entry point for everyone who wants to implement a Truffle based language. By providing an
40 * implementation of this type and registering it using {@link Registration} annotation, your 55 * implementation of this type and registering it using {@link Registration} annotation, your
41 * language becomes accessible to users of the {@link com.oracle.truffle.api.vm.TruffleVM Truffle 56 * language becomes accessible to users of the {@link com.oracle.truffle.api.vm.TruffleVM Truffle
171 * @param object the object to check 186 * @param object the object to check
172 * @return <code>true</code> if this language can deal with such object in native way 187 * @return <code>true</code> if this language can deal with such object in native way
173 */ 188 */
174 protected abstract boolean isObjectOfLanguage(Object object); 189 protected abstract boolean isObjectOfLanguage(Object object);
175 190
191 @Deprecated
176 protected abstract ToolSupportProvider getToolSupport(); 192 protected abstract ToolSupportProvider getToolSupport();
177 193
194 @Deprecated
178 protected abstract DebugSupportProvider getDebugSupport(); 195 protected abstract DebugSupportProvider getDebugSupport();
196
197 /**
198 * Gets visualization services for language-specific information.
199 */
200 protected abstract Visualizer getVisualizer();
201
202 /**
203 * Enables AST probing on all subsequently created ASTs (sources parsed).
204 *
205 * @param astProber optional AST prober to enable; the default for the language used if
206 * {@code null}
207 */
208 @Deprecated
209 protected abstract void enableASTProbing(ASTProber astProber);
210
211 /**
212 * Gets the current specification for AST instrumentation for the language; <em>empty</em> if
213 * none.
214 */
215 protected abstract List<ASTProber> getASTProbers();
216
217 /**
218 * Runs source code in a halted execution context, or at top level.
219 *
220 * @param source the code to run
221 * @param node node where execution halted, {@code null} if no execution context
222 * @param mFrame frame where execution halted, {@code null} if no execution context
223 * @return result of running the code in the context, or at top level if no execution context.
224 * @throws IOException if the evaluation cannot be performed
225 */
226 protected abstract Object evalInContext(Source source, Node node, MaterializedFrame mFrame) throws IOException;
227
228 /**
229 * Creates a language-specific factory to produce instances of {@link AdvancedInstrumentRoot}
230 * that, when executed, computes the result of a textual expression in the language; used to
231 * create an
232 * {@linkplain Instrument#create(AdvancedInstrumentResultListener, AdvancedInstrumentRootFactory, Class, String)
233 * Advanced Instrument}.
234 *
235 * @param expr a guest language expression
236 * @param resultListener optional listener for the result of each evaluation.
237 * @return a new factory
238 * @throws IOException if the factory cannot be created, for example if the expression is badly
239 * formed.
240 */
241 protected abstract AdvancedInstrumentRootFactory createAdvancedInstrumentRootFactory(String expr, AdvancedInstrumentResultListener resultListener) throws IOException;
179 242
180 /** 243 /**
181 * Allows a language implementor to create a node that can effectively lookup up the context 244 * Allows a language implementor to create a node that can effectively lookup up the context
182 * associated with current execution. The context is created by 245 * associated with current execution. The context is created by
183 * {@link #createContext(com.oracle.truffle.api.TruffleLanguage.Env)} method. 246 * {@link #createContext(com.oracle.truffle.api.TruffleLanguage.Env)} method.
330 throw new IOException(ex); 393 throw new IOException(ex);
331 } 394 }
332 } 395 }
333 396
334 @Override 397 @Override
398 protected AdvancedInstrumentRootFactory createAdvancedInstrumentRootFactory(Object vm, Class<? extends TruffleLanguage> languageClass, String expr,
399 AdvancedInstrumentResultListener resultListener) throws IOException {
400
401 final TruffleLanguage language = findLanguageImpl(vm, languageClass);
402 return language.createAdvancedInstrumentRootFactory(expr, resultListener);
403 }
404
405 @Override
335 protected Object findExportedSymbol(TruffleLanguage.Env env, String globalName, boolean onlyExplicit) { 406 protected Object findExportedSymbol(TruffleLanguage.Env env, String globalName, boolean onlyExplicit) {
336 return env.langCtx.findExportedSymbol(globalName, onlyExplicit); 407 return env.langCtx.findExportedSymbol(globalName, onlyExplicit);
337 } 408 }
338 409
339 @Override 410 @Override
355 protected Object findContext(Env env) { 426 protected Object findContext(Env env) {
356 return env.langCtx.ctx; 427 return env.langCtx.ctx;
357 } 428 }
358 429
359 @Override 430 @Override
431 protected List<ASTProber> getASTProbers(Object vm, Class<? extends TruffleLanguage> languageClass) {
432 TruffleLanguage impl = findLanguageImpl(vm, languageClass);
433 return impl.getASTProbers();
434 }
435
436 @SuppressWarnings("deprecation")
437 @Override
360 protected ToolSupportProvider getToolSupport(TruffleLanguage<?> l) { 438 protected ToolSupportProvider getToolSupport(TruffleLanguage<?> l) {
361 return l.getToolSupport(); 439 return l.getToolSupport();
362 } 440 }
363 441
442 @SuppressWarnings("deprecation")
364 @Override 443 @Override
365 protected DebugSupportProvider getDebugSupport(TruffleLanguage<?> l) { 444 protected DebugSupportProvider getDebugSupport(TruffleLanguage<?> l) {
366 return l.getDebugSupport(); 445 return l.getDebugSupport();
367 } 446 }
368 } 447 }