Mercurial > hg > graal-compiler

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/ExecutionContext.java @ 15779:8c34e2cc4add

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: significant reorganization of the instrumentation framework's implementation and connection to the runtime ExecutionContext, with some new features, including a Tag-based "trap" mechanisms.
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 19 May 2014 17:14:36 -0700
parents bb9473723904
children eb947cc7bff9
comparison
equal deleted inserted replaced
15632:dcaf3993ad17 15779:8c34e2cc4add
25 package com.oracle.truffle.api; 25 package com.oracle.truffle.api;
26 26
27 import java.util.*; 27 import java.util.*;
28 28
29 import com.oracle.truffle.api.instrument.*; 29 import com.oracle.truffle.api.instrument.*;
30 import com.oracle.truffle.api.instrument.impl.*;
30 import com.oracle.truffle.api.source.*; 31 import com.oracle.truffle.api.source.*;
31 32
32 /** 33 /**
33 * Access to information and basic services in the runtime context for a Truffle-implemented guest 34 * Access to information and basic services in the runtime context for a Truffle-implemented guest
34 * language. 35 * language.
35 * <p> 36 * <p>
36 * <strong>Disclaimer:</strong> this interface is under development and will change. 37 * <strong>Disclaimer:</strong> this class is under development and will change.
37 */ 38 */
38 public interface ExecutionContext { 39 public abstract class ExecutionContext {
40
41 private final ProbeManager probeManager = new ProbeManager();
42 private final SourceManager sourceManager = new SourceManager();
43 private final List<SourceListener> sourceListeners = new ArrayList<>();
44 private Visualizer visualizer = new DefaultVisualizer();
45
46 protected ExecutionContext() {
47 }
48
49 public void initialize() {
50 setSourceCallback(new SourceCallback() {
51
52 public void startLoading(Source source) {
53 for (SourceListener listener : sourceListeners) {
54 listener.loadStarting(source);
55 }
56 }
57
58 public void endLoading(Source source) {
59 for (SourceListener listener : sourceListeners) {
60 listener.loadEnding(source);
61 }
62 }
63 });
64 }
65
66 /**
67 * Gets access to source management services.
68 */
69 public final SourceManager getSourceManager() {
70 return sourceManager;
71 }
72
73 /**
74 * Registers a tool interested in being notified about the loading of {@link Source}s.
75 */
76 public final void addSourceListener(SourceListener listener) {
77 assert listener != null;
78 sourceListeners.add(listener);
79 }
80
81 /**
82 * Registers a tool interested in being notified about the insertion of a newly created
83 * {@link Probe} into a Truffle AST.
84 */
85 public final void addProbeListener(ProbeListener listener) {
86 probeManager.addProbeListener(listener);
87 }
88
89 /**
90 * Return the (possibly newly created) {@link Probe} uniquely associated with a particular
91 * source code location. A newly created probe carries no tags.
92 *
93 * @return a probe uniquely associated with an extent of guest language source code.
94 */
95 public final Probe getProbe(SourceSection sourceSection) {
96 return probeManager.getProbe(sourceSection);
97 }
98
99 /**
100 * Returns all existing probes with specific tag, or all probes if {@code tag = null}; empty
101 * collection if no probes found.
102 */
103 public final Collection<Probe> findProbesTaggedAs(PhylumTag tag) {
104 return probeManager.findProbesTaggedAs(tag);
105 }
106
107 /**
108 * Returns all existing probes with first character on a specified line; empty collection if no
109 * probes found.
110 */
111 public final Collection<Probe> findProbesByLine(SourceLineLocation lineLocation) {
112 return probeManager.findProbesByLine(lineLocation);
113 }
114
115 /**
116 * Sets a trap that will make a callback at any AST location where a existing probe holds a
117 * specified tag; only one trap may be set at a time.
118 *
119 * @throws IllegalStateException if a trap is already set
120 */
121 public final void setPhylumTrap(PhylumTrap trap) throws IllegalStateException {
122 // TODO (mlvdv) consider allowing multiple traps (without inhibiting Truffle inlining)
123 probeManager.setPhylumTrap(trap);
124 }
125
126 /**
127 * Clears a trap that will halt execution; only one trap may be set at a time.
128 *
129 * @throws IllegalStateException if no trap is set.
130 */
131 public final void clearPhylumTrap() {
132 probeManager.clearPhylumTrap();
133 }
134
135 /**
136 * Access to information visualization services for the specific language.
137 */
138 public final Visualizer getVisualizer() {
139 return visualizer;
140 }
141
142 /**
143 * Assign guest language-specific visualization support for tools. This must be assigned outside
144 * the implementation context to avoid build circularities.
145 */
146 public final void setVisualizer(Visualizer visualizer) {
147 this.visualizer = visualizer;
148 }
39 149
40 /** 150 /**
41 * Gets the name of the language, possibly with version number. in short enough form that it 151 * Gets the name of the language, possibly with version number. in short enough form that it
42 * might be used for an interactive prompt. 152 * might be used for an interactive prompt.
43 */ 153 */
44 String getLanguageShortName(); 154 public abstract String getLanguageShortName();
45
46 /**
47 * Gets access to source management services.
48 */
49 SourceManager getSourceManager();
50
51 /**
52 * Registers a tool interested in being notified of events related to the loading of sources.
53 */
54 void addSourceListener(SourceListener listener);
55 155
56 /** 156 /**
57 * Add instrumentation to subsequently constructed Truffle ASTs for the guest language; every 157 * Add instrumentation to subsequently constructed Truffle ASTs for the guest language; every
58 * one added will have the opportunity to add instrumentation. 158 * one added will have the opportunity to add instrumentation.
59 * 159 *
60 * @throws IllegalStateException if AST instrumentation not enabled 160 * @throws IllegalStateException if AST instrumentation not enabled
61 * @throws IllegalArgumentException if prober not usable for the guest language implementation. 161 * @throws IllegalArgumentException if prober not usable for the guest language implementation.
62 */ 162 */
63 void addNodeProber(ASTNodeProber nodeProber) throws IllegalStateException, IllegalArgumentException; 163 public abstract void addNodeProber(ASTNodeProber nodeProber) throws IllegalStateException, IllegalArgumentException;
64 164
65 /** 165 /**
66 * Registers a tool interested in being notified about the insertion of a newly created 166 * Assigns a guest language-specific manager for using {@link ASTNodeProber}s added by tools to
67 * {@link Probe} into a Truffle AST. 167 * instrument ASTs with {@link Probe}s at specified nodes. This must be assigned outside the
168 * implementation context to avoid build circularities. It must also be set before any
169 * instrumentation probe implementations are assigned.
68 */ 170 */
69 void addProbeListener(ProbeListener listener); 171 public abstract void setASTProber(ASTProber astProber);
70 172
71 /** 173 /**
72 * Return the (possibly newly created) {@link Probe} uniquely associated with a particular 174 * Establishes source event reporting
73 * source code location. A newly created probe carries no tags.
74 *
75 * @return a probe uniquely associated with an extent of guest language source code.
76 */ 175 */
77 Probe getProbe(SourceSection sourceSection); 176 protected abstract void setSourceCallback(SourceCallback sourceCallback);
78 177
79 /**
80 * Returns all existing probes with specific tag, or all probes if {@code tag = null}; empty
81 * collection if no probes found.
82 */
83 Collection<Probe> findProbesTaggedAs(PhylumTag tag);
84
85 /**
86 * Returns all existing probes with first character on a specified line; empty collection if no
87 * probes found.
88 */
89 Collection<Probe> findProbesByLine(SourceLineLocation lineLocation);
90
91 /**
92 * Sets a trap that will make a callback at any AST location where a existing probe holds a
93 * specified tag; only one trap may be set at a time.
94 *
95 * @throws IllegalStateException if a trap is already set
96 */
97 void setTrap(PhylumTrap trap) throws IllegalStateException;
98
99 /**
100 * Clears a trap that will halt execution; only one trap may be set at a time.
101 *
102 * @throws IllegalStateException if no trap is set.
103 */
104 void clearTrap() throws IllegalStateException;
105
106 /**
107 * Access to information visualization services for the specific language.
108 */
109 Visualizer getVisualizer();
110 } 178 }