Mercurial > hg > truffle

comparison truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/TruffleLanguage.java @ 22094:0058a9461865

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/instrumentation: minor Javadoc fixes
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 17 Aug 2015 15:24:22 -0700
parents ff531952a91c
children cf19259edf87
comparison
equal deleted inserted replaced
22093:0f0e34039769 22094:0058a9461865
37 import java.util.Collections; 37 import java.util.Collections;
38 import java.util.Map; 38 import java.util.Map;
39 import java.util.WeakHashMap; 39 import java.util.WeakHashMap;
40 40
41 /** 41 /**
42 * An entry point for everyone who wants to implement a Truffle based language. By providing 42 * An entry point for everyone who wants to implement a Truffle based language. By providing an
43 * implementation of this type and registering it using {@link Registration} annotation, your 43 * implementation of this type and registering it using {@link Registration} annotation, your
44 * language becomes accessible to users of the {@link TruffleVM Truffle virtual machine} - all they 44 * language becomes accessible to users of the {@link TruffleVM Truffle virtual machine} - all they
45 * will need to do is to include your JAR into their application and all the Truffle goodies (multi 45 * will need to do is to include your JAR into their application and all the Truffle goodies
46 * language support, multitenant hosting, debugging, etc.) will be made available to them. 46 * (multi-language support, multitenant hosting, debugging, etc.) will be made available to them.
47 * 47 *
48 * @param <C> internal state of the language associated with every thread that is executing program 48 * @param <C> internal state of the language associated with every thread that is executing program
49 * {@link #parse(com.oracle.truffle.api.source.Source, com.oracle.truffle.api.nodes.Node, java.lang.String...) 49 * {@link #parse(com.oracle.truffle.api.source.Source, com.oracle.truffle.api.nodes.Node, java.lang.String...)
50 * parsed} by the language 50 * parsed} by the language
51 */ 51 */
52 public abstract class TruffleLanguage<C> { 52 public abstract class TruffleLanguage<C> {
97 * time the {@link TruffleLanguage language} is used by a new {@link TruffleVM} or in a new 97 * time the {@link TruffleLanguage language} is used by a new {@link TruffleVM} or in a new
98 * thread, the system calls this method to let the {@link TruffleLanguage language} prepare for 98 * thread, the system calls this method to let the {@link TruffleLanguage language} prepare for
99 * <em>execution</em>. The returned execution context is completely language specific; it is 99 * <em>execution</em>. The returned execution context is completely language specific; it is
100 * however expected it will contain reference to here-in provided <code>env</code> and adjust 100 * however expected it will contain reference to here-in provided <code>env</code> and adjust
101 * itself according to parameters provided by the <code>env</code> object. 101 * itself according to parameters provided by the <code>env</code> object.
102 * 102 *
103 * @param env the environment the language is supposed to operate in 103 * @param env the environment the language is supposed to operate in
104 * @return internal data of the language in given environment 104 * @return internal data of the language in given environment
105 */ 105 */
106 protected abstract C createContext(Env env); 106 protected abstract C createContext(Env env);
107 107
177 177
178 /** 178 /**
179 * Allows a language implementor to create a node that can effectively lookup up the context 179 * Allows a language implementor to create a node that can effectively lookup up the context
180 * associated with current execution. The context is created by 180 * associated with current execution. The context is created by
181 * {@link #createContext(com.oracle.truffle.api.TruffleLanguage.Env)} method. 181 * {@link #createContext(com.oracle.truffle.api.TruffleLanguage.Env)} method.
182 * 182 *
183 * @return node to be inserted into program to effectively find out current execution context 183 * @return node to be inserted into program to effectively find out current execution context
184 * for this language 184 * for this language
185 */ 185 */
186 @SuppressWarnings({"rawtypes", "unchecked"}) 186 @SuppressWarnings({"rawtypes", "unchecked"})
187 protected final Node createFindContextNode() { 187 protected final Node createFindContextNode() {
189 return new FindContextNode(c); 189 return new FindContextNode(c);
190 } 190 }
191 191
192 /** 192 /**
193 * Uses the {@link #createFindContextNode()} node to obtain the current context. 193 * Uses the {@link #createFindContextNode()} node to obtain the current context.
194 * 194 *
195 * @param n the node created by this language's {@link #createFindContextNode()} 195 * @param n the node created by this language's {@link #createFindContextNode()}
196 * @return the context created by 196 * @return the context created by
197 * {@link #createContext(com.oracle.truffle.api.TruffleLanguage.Env)} method at the 197 * {@link #createContext(com.oracle.truffle.api.TruffleLanguage.Env)} method at the
198 * beginning of the language execution 198 * beginning of the language execution
199 * @throws ClassCastException if the node has not been created by <code>this</code>. 199 * @throws ClassCastException if the node has not been created by <code>this</code>.