Mercurial > hg > truffle

comparison truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/TruffleLanguage.java @ 22128:f879b1fe3773

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Separating the TruffleVM into its own project makes it possible to cleanup various system parts interations
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Thu, 03 Sep 2015 16:38:45 +0200
parents c2cb9f1c8688
children c334865b9d42
comparison
equal deleted inserted replaced
22127:5a0cccf023c4 22128:f879b1fe3773
30 import com.oracle.truffle.api.debug.*; 30 import com.oracle.truffle.api.debug.*;
31 import com.oracle.truffle.api.impl.*; 31 import com.oracle.truffle.api.impl.*;
32 import com.oracle.truffle.api.instrument.*; 32 import com.oracle.truffle.api.instrument.*;
33 import com.oracle.truffle.api.nodes.Node; 33 import com.oracle.truffle.api.nodes.Node;
34 import com.oracle.truffle.api.source.*; 34 import com.oracle.truffle.api.source.*;
35 import com.oracle.truffle.api.vm.*;
36 import com.oracle.truffle.api.vm.TruffleVM.Language;
37 import java.util.Collections; 35 import java.util.Collections;
38 import java.util.Map; 36 import java.util.Map;
39 import java.util.WeakHashMap; 37 import java.util.WeakHashMap;
40 38
41 /** 39 /**
42 * An entry point for everyone who wants to implement a Truffle based language. By providing an 40 * 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 41 * 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 42 * language becomes accessible to users of the {@link com.oracle.truffle.api.vm.TruffleVM Truffle
45 * will need to do is to include your JAR into their application and all the Truffle goodies 43 * virtual machine} - all they will need to do is to include your JAR into their application and all
46 * (multi-language support, multitenant hosting, debugging, etc.) will be made available to them. 44 * the Truffle goodies (multi-language support, multitenant hosting, debugging, etc.) will be made
45 * available to them.
47 * 46 *
48 * @param <C> internal state of the language associated with every thread that is executing program 47 * @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...) 48 * {@link #parse(com.oracle.truffle.api.source.Source, com.oracle.truffle.api.nodes.Node, java.lang.String...)
50 * parsed} by the language 49 * parsed} by the language
51 */ 50 */
51 @SuppressWarnings("javadoc")
52 public abstract class TruffleLanguage<C> { 52 public abstract class TruffleLanguage<C> {
53 /** 53 /**
54 * Constructor to be called by subclasses. 54 * Constructor to be called by subclasses.
55 */ 55 */
56 protected TruffleLanguage() { 56 protected TruffleLanguage() {
57 } 57 }
58 58
59 /** 59 /**
60 * The annotation to use to register your language to the {@link TruffleVM Truffle} system. By 60 * The annotation to use to register your language to the
61 * annotating your implementation of {@link TruffleLanguage} by this annotation you are just a 61 * {@link com.oracle.truffle.api.vm.TruffleVM Truffle} system. By annotating your implementation
62 * of {@link TruffleLanguage} by this annotation you are just a
62 * <em>one JAR drop to the class path</em> away from your users. Once they include your JAR in 63 * <em>one JAR drop to the class path</em> away from your users. Once they include your JAR in
63 * their application, your language will be available to the {@link TruffleVM Truffle virtual 64 * their application, your language will be available to the
64 * machine}. 65 * {@link com.oracle.truffle.api.vm.TruffleVM Truffle virtual machine}.
65 */ 66 */
66 @Retention(RetentionPolicy.SOURCE) 67 @Retention(RetentionPolicy.SOURCE)
67 @Target(ElementType.TYPE) 68 @Target(ElementType.TYPE)
68 public @interface Registration { 69 public @interface Registration {
69 /** 70 /**
70 * Unique name of your language. This name will be exposed to users via the 71 * Unique name of your language. This name will be exposed to users via the
71 * {@link Language#getName()} getter. 72 * {@link com.oracle.truffle.api.vm.TruffleVM.Language#getName()} getter.
72 * 73 *
73 * @return identifier of your language 74 * @return identifier of your language
74 */ 75 */
75 String name(); 76 String name();
76 77
77 /** 78 /**
78 * Unique string identifying the language version. This name will be exposed to users via 79 * Unique string identifying the language version. This name will be exposed to users via
79 * the {@link Language#getVersion()} getter. 80 * the {@link com.oracle.truffle.api.vm.TruffleVM.Language#getVersion()} getter.
80 * 81 *
81 * @return version of your language 82 * @return version of your language
82 */ 83 */
83 String version(); 84 String version();
84 85
85 /** 86 /**
86 * List of MIME types associated with your language. Users will use them (directly or 87 * List of MIME types associated with your language. Users will use them (directly or
87 * indirectly) when {@link TruffleVM#eval(com.oracle.truffle.api.source.Source) executing} 88 * indirectly) when
88 * their code snippets or their {@link Source files}. 89 * {@link com.oracle.truffle.api.vm.TruffleVM#eval(com.oracle.truffle.api.source.Source)
90 * executing} their code snippets or their {@link Source files}.
89 * 91 *
90 * @return array of MIME types assigned to your language files 92 * @return array of MIME types assigned to your language files
91 */ 93 */
92 String[] mimeType(); 94 String[] mimeType();
93 } 95 }
94 96
95 /** 97 /**
96 * Creates internal representation of the executing context suitable for given environment. Each 98 * Creates internal representation of the executing context suitable for given environment. Each
97 * time the {@link TruffleLanguage language} is used by a new {@link TruffleVM} or in a new 99 * time the {@link TruffleLanguage language} is used by a new
98 * thread, the system calls this method to let the {@link TruffleLanguage language} prepare for 100 * {@link com.oracle.truffle.api.vm.TruffleVM} or in a new thread, the system calls this method
99 * <em>execution</em>. The returned execution context is completely language specific; it is 101 * to let the {@link TruffleLanguage language} prepare for <em>execution</em>. The returned
100 * however expected it will contain reference to here-in provided <code>env</code> and adjust 102 * execution context is completely language specific; it is however expected it will contain
101 * itself according to parameters provided by the <code>env</code> object. 103 * reference to here-in provided <code>env</code> and adjust itself according to parameters
104 * provided by the <code>env</code> object.
102 * 105 *
103 * @param env the environment the language is supposed to operate in 106 * @param env the environment the language is supposed to operate in
104 * @return internal data of the language in given environment 107 * @return internal data of the language in given environment
105 */ 108 */
106 protected abstract C createContext(Env env); 109 protected abstract C createContext(Env env);
120 * {@link CallTarget#call(java.lang.Object...)} 123 * {@link CallTarget#call(java.lang.Object...)}
121 * @return a call target to invoke which also keeps in memory the {@link Node} tree representing 124 * @return a call target to invoke which also keeps in memory the {@link Node} tree representing
122 * just parsed <code>code</code> 125 * just parsed <code>code</code>
123 * @throws IOException thrown when I/O or parsing goes wrong. Here-in thrown exception is 126 * @throws IOException thrown when I/O or parsing goes wrong. Here-in thrown exception is
124 * propagate to the user who called one of <code>eval</code> methods of 127 * propagate to the user who called one of <code>eval</code> methods of
125 * {@link TruffleVM} 128 * {@link com.oracle.truffle.api.vm.TruffleVM}
126 */ 129 */
127 protected abstract CallTarget parse(Source code, Node context, String... argumentNames) throws IOException; 130 protected abstract CallTarget parse(Source code, Node context, String... argumentNames) throws IOException;
128 131
129 /** 132 /**
130 * Called when some other language is seeking for a global symbol. This method is supposed to do 133 * Called when some other language is seeking for a global symbol. This method is supposed to do
231 * {@link TruffleLanguage} receives instance of the environment before any code is executed upon 234 * {@link TruffleLanguage} receives instance of the environment before any code is executed upon
232 * it. The environment has knowledge of all active languages and can exchange symbols between 235 * it. The environment has knowledge of all active languages and can exchange symbols between
233 * them. 236 * them.
234 */ 237 */
235 public static final class Env { 238 public static final class Env {
236 private final TruffleVM vm; 239 private final Object vm;
237 private final TruffleLanguage<?> lang; 240 private final TruffleLanguage<?> lang;
238 private final LangCtx<?> langCtx; 241 private final LangCtx<?> langCtx;
239 private final Reader in; 242 private final Reader in;
240 private final Writer err; 243 private final Writer err;
241 private final Writer out; 244 private final Writer out;
242 245
243 Env(TruffleVM vm, TruffleLanguage<?> lang, Writer out, Writer err, Reader in) { 246 Env(Object vm, TruffleLanguage<?> lang, Writer out, Writer err, Reader in) {
244 this.vm = vm; 247 this.vm = vm;
245 this.in = in; 248 this.in = in;
246 this.err = err; 249 this.err = err;
247 this.out = out; 250 this.out = out;
248 this.lang = lang; 251 this.lang = lang;
261 public Object importSymbol(String globalName) { 264 public Object importSymbol(String globalName) {
262 return API.importSymbol(vm, lang, globalName); 265 return API.importSymbol(vm, lang, globalName);
263 } 266 }
264 267
265 /** 268 /**
266 * Input associated with this {@link TruffleVM}. 269 * Input associated with {@link com.oracle.truffle.api.vm.TruffleVM} this language is being
270 * executed in.
267 * 271 *
268 * @return reader, never <code>null</code> 272 * @return reader, never <code>null</code>
269 */ 273 */
270 public Reader stdIn() { 274 public Reader stdIn() {
271 return in; 275 return in;
272 } 276 }
273 277
274 /** 278 /**
275 * Standard output writer for this {@link TruffleVM}. 279 * Standard output writer for {@link com.oracle.truffle.api.vm.TruffleVM} this language is
280 * being executed in.
276 * 281 *
277 * @return writer, never <code>null</code> 282 * @return writer, never <code>null</code>
278 */ 283 */
279 public Writer stdOut() { 284 public Writer stdOut() {
280 return out; 285 return out;
281 } 286 }
282 287
283 /** 288 /**
284 * Standard error writer for this {@link TruffleVM}. 289 * Standard error writer for {@link com.oracle.truffle.api.vm.TruffleVM} this language is
290 * being executed in.
285 * 291 *
286 * @return writer, never <code>null</code> 292 * @return writer, never <code>null</code>
287 */ 293 */
288 public Writer stdErr() { 294 public Writer stdErr() {
289 return err; 295 return err;
293 private static final AccessAPI API = new AccessAPI(); 299 private static final AccessAPI API = new AccessAPI();
294 300
295 @SuppressWarnings("rawtypes") 301 @SuppressWarnings("rawtypes")
296 private static final class AccessAPI extends Accessor { 302 private static final class AccessAPI extends Accessor {
297 @Override 303 @Override
298 protected Env attachEnv(TruffleVM vm, TruffleLanguage<?> language, Writer stdOut, Writer stdErr, Reader stdIn) { 304 protected Env attachEnv(Object vm, TruffleLanguage<?> language, Writer stdOut, Writer stdErr, Reader stdIn) {
299 Env env = new Env(vm, language, stdOut, stdErr, stdIn); 305 Env env = new Env(vm, language, stdOut, stdErr, stdIn);
300 return env; 306 return env;
301 } 307 }
302 308
303 @Override 309 @Override
304 public Object importSymbol(TruffleVM vm, TruffleLanguage<?> queryingLang, String globalName) { 310 protected Object importSymbol(Object vm, TruffleLanguage<?> queryingLang, String globalName) {
305 return super.importSymbol(vm, queryingLang, globalName); 311 return super.importSymbol(vm, queryingLang, globalName);
306 } 312 }
307 313
308 private static final Map<Source, CallTarget> COMPILED = Collections.synchronizedMap(new WeakHashMap<Source, CallTarget>()); 314 private static final Map<Source, CallTarget> COMPILED = Collections.synchronizedMap(new WeakHashMap<Source, CallTarget>());
309 315
328 protected Object findExportedSymbol(TruffleLanguage.Env env, String globalName, boolean onlyExplicit) { 334 protected Object findExportedSymbol(TruffleLanguage.Env env, String globalName, boolean onlyExplicit) {
329 return env.langCtx.findExportedSymbol(globalName, onlyExplicit); 335 return env.langCtx.findExportedSymbol(globalName, onlyExplicit);
330 } 336 }
331 337
332 @Override 338 @Override
333 protected Env findLanguage(TruffleVM vm, Class<? extends TruffleLanguage> languageClass) { 339 protected Env findLanguage(Object vm, Class<? extends TruffleLanguage> languageClass) {
334 return super.findLanguage(vm, languageClass); 340 return super.findLanguage(vm, languageClass);
335 } 341 }
336 342
337 @Override 343 @Override
338 protected TruffleLanguage<?> findLanguage(Env env) { 344 protected TruffleLanguage<?> findLanguage(Env env) {