Mercurial > hg > truffle

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/vm/TruffleVM.java @ 21649:1c76a5662753

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge with 645f170013a451083414ff695412c465e9d2ebf0
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 01 Jun 2015 17:47:28 -0700
parents 31fc2fce38f3
children 2f9e4d984d16
comparison
equal deleted inserted replaced
21648:610d76a131cd 21649:1c76a5662753
1 /* 1 /*
2 * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. 2 * Copyright (c) 2014, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 * 4 *
5 * This code is free software; you can redistribute it and/or modify it 5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as 6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this 7 * published by the Free Software Foundation. Oracle designates this
38 import com.oracle.truffle.api.source.*; 38 import com.oracle.truffle.api.source.*;
39 39
40 /** 40 /**
41 * Virtual machine for Truffle based languages. Use {@link #newVM()} to create new isolated virtual 41 * Virtual machine for Truffle based languages. Use {@link #newVM()} to create new isolated virtual
42 * machine ready for execution of various languages. All the languages in a single virtual machine 42 * machine ready for execution of various languages. All the languages in a single virtual machine
43 * see each other exported global symbols and can co-operate. Use {@link #newVM()} multiple times to 43 * see each other exported global symbols and can cooperate. Use {@link #newVM()} multiple times to
44 * create different, isolated virtual machines completely separated from each other. 44 * create different, isolated virtual machines completely separated from each other.
45 * <p> 45 * <p>
46 * Once instantiated use {@link #eval(java.net.URI)} with a reference to a file or URL or directly 46 * Once instantiated use {@link #eval(java.net.URI)} with a reference to a file or URL or directly
47 * pass code snippet into the virtual machine via {@link #eval(java.lang.String, java.lang.String)}. 47 * pass code snippet into the virtual machine via {@link #eval(java.lang.String, java.lang.String)}.
48 * Support for individual languages is initialized on demand - e.g. once a file of certain mime type 48 * Support for individual languages is initialized on demand - e.g. once a file of certain MIME type
49 * is about to be processed, its appropriate engine (if found), is initialized. Once an engine gets 49 * is about to be processed, its appropriate engine (if found), is initialized. Once an engine gets
50 * initialized, it remains so, until the virtual machine isn't garbage collected. 50 * initialized, it remains so, until the virtual machine isn't garbage collected.
51 * <p> 51 * <p>
52 * The <code>TruffleVM</code> is single-threaded and tries to enforce that. It records the thread it 52 * The <code>TruffleVM</code> is single-threaded and tries to enforce that. It records the thread it
53 * has been {@link Builder#build() created} by and checks that all subsequent calls are coming from 53 * has been {@link Builder#build() created} by and checks that all subsequent calls are coming from
188 err = w; 188 err = w;
189 return this; 189 return this;
190 } 190 }
191 191
192 /** 192 /**
193 * Changes the defaut input for languages running in <em>to be created</em> 193 * Changes the default input for languages running in <em>to be created</em>
194 * {@link TruffleVM virtual machine}. The default is to use {@link System#out}. 194 * {@link TruffleVM virtual machine}. The default is to use {@link System#out}.
195 * 195 *
196 * @param r the reader to use as input 196 * @param r the reader to use as input
197 * @return instance of this builder 197 * @return instance of this builder
198 */ 198 */
222 } 222 }
223 223
224 /** 224 /**
225 * Descriptions of languages supported in this Truffle virtual machine. 225 * Descriptions of languages supported in this Truffle virtual machine.
226 * 226 *
227 * @return an immutable map with keys being mimetypes and values the {@link Language 227 * @return an immutable map with keys being MIME types and values the {@link Language
228 * descriptions} of associated languages 228 * descriptions} of associated languages
229 */ 229 */
230 public Map<String, Language> getLanguages() { 230 public Map<String, Language> getLanguages() {
231 return Collections.unmodifiableMap(langs); 231 return Collections.unmodifiableMap(langs);
232 } 232 }
233 233
234 /** 234 /**
235 * Evaluates file located on a given URL. Is equivalent to loading the content of a file and 235 * Evaluates file located on a given URL. Is equivalent to loading the content of a file and
236 * executing it via {@link #eval(java.lang.String, java.lang.String)} with a mime type guess 236 * executing it via {@link #eval(java.lang.String, java.lang.String)} with a MIME type guess
237 * based on the file's extension and/or content. 237 * based on the file's extension and/or content.
238 * 238 *
239 * @param location the location of a file to execute 239 * @param location the location of a file to execute
240 * @return result of a processing the file, possibly <code>null</code> 240 * @return result of a processing the file, possibly <code>null</code>
241 * @throws IOException exception to signal I/O problems or problems with processing the file's 241 * @throws IOException exception to signal I/O problems or problems with processing the file's
261 URLConnection conn = url.openConnection(); 261 URLConnection conn = url.openConnection();
262 mimeType = conn.getContentType(); 262 mimeType = conn.getContentType();
263 } 263 }
264 TruffleLanguage l = getTruffleLang(mimeType); 264 TruffleLanguage l = getTruffleLang(mimeType);
265 if (l == null) { 265 if (l == null) {
266 throw new IOException("No language for " + location + " with mime type " + mimeType + " found. Supported types: " + langs.keySet()); 266 throw new IOException("No language for " + location + " with MIME type " + mimeType + " found. Supported types: " + langs.keySet());
267 } 267 }
268 return SPI.eval(l, s); 268 return SPI.eval(l, s);
269 } 269 }
270 270
271 /** 271 /**
272 * Evaluates code snippet. Chooses a language registered for a given mime type (throws 272 * Evaluates code snippet. Chooses a language registered for a given MIME type (throws
273 * {@link IOException} if there is none). And passes the specified code to it for execution. 273 * {@link IOException} if there is none). And passes the specified code to it for execution.
274 * 274 *
275 * @param mimeType mime type of the code snippet - chooses the right language 275 * @param mimeType MIME type of the code snippet - chooses the right language
276 * @param reader the source of code snippet to execute 276 * @param reader the source of code snippet to execute
277 * @return result of an exceution, possibly <code>null</code> 277 * @return result of an execution, possibly <code>null</code>
278 * @throws IOException thrown to signal errors while processing the code 278 * @throws IOException thrown to signal errors while processing the code
279 */ 279 */
280 public Object eval(String mimeType, Reader reader) throws IOException { 280 public Object eval(String mimeType, Reader reader) throws IOException {
281 checkThread(); 281 checkThread();
282 TruffleLanguage l = getTruffleLang(mimeType); 282 TruffleLanguage l = getTruffleLang(mimeType);
283 if (l == null) { 283 if (l == null) {
284 throw new IOException("No language for mime type " + mimeType + " found. Supported types: " + langs.keySet()); 284 throw new IOException("No language for MIME type " + mimeType + " found. Supported types: " + langs.keySet());
285 } 285 }
286 return SPI.eval(l, Source.fromReader(reader, mimeType)); 286 return SPI.eval(l, Source.fromReader(reader, mimeType));
287 } 287 }
288 288
289 /** 289 /**
290 * Evaluates code snippet. Chooses a language registered for a given mime type (throws 290 * Evaluates code snippet. Chooses a language registered for a given MIME type (throws
291 * {@link IOException} if there is none). And passes the specified code to it for execution. 291 * {@link IOException} if there is none). And passes the specified code to it for execution.
292 * 292 *
293 * @param mimeType mime type of the code snippet - chooses the right language 293 * @param mimeType MIME type of the code snippet - chooses the right language
294 * @param code the code snippet to execute 294 * @param code the code snippet to execute
295 * @return result of an exceution, possibly <code>null</code> 295 * @return result of an execution, possibly <code>null</code>
296 * @throws IOException thrown to signal errors while processing the code 296 * @throws IOException thrown to signal errors while processing the code
297 */ 297 */
298 public Object eval(String mimeType, String code) throws IOException { 298 public Object eval(String mimeType, String code) throws IOException {
299 checkThread(); 299 checkThread();
300 TruffleLanguage l = getTruffleLang(mimeType); 300 TruffleLanguage l = getTruffleLang(mimeType);
301 if (l == null) { 301 if (l == null) {
302 throw new IOException("No language for mime type " + mimeType + " found. Supported types: " + langs.keySet()); 302 throw new IOException("No language for MIME type " + mimeType + " found. Supported types: " + langs.keySet());
303 } 303 }
304 return SPI.eval(l, Source.fromText(code, mimeType)); 304 return SPI.eval(l, Source.fromText(code, mimeType));
305 } 305 }
306 306
307 /** 307 /**
308 * Looks global symbol provided by one of initialized languages up. First of all execute your 308 * Looks global symbol provided by one of initialized languages up. First of all execute your
309 * program via one of your {@link #eval(java.lang.String, java.lang.String)} and then look 309 * program via one of your {@link #eval(java.lang.String, java.lang.String)} and then look
310 * expected symbol up using this method. 310 * expected symbol up using this method.
311 * <p> 311 * <p>
312 * The names of the symbols are language dependant, but for example the Java language bindings 312 * The names of the symbols are language dependent, but for example the Java language bindings
313 * follow the specification for method references: 313 * follow the specification for method references:
314 * <ul> 314 * <ul>
315 * <li>"java.lang.Exception::new" is a reference to constructor of {@link Exception} 315 * <li>"java.lang.Exception::new" is a reference to constructor of {@link Exception}
316 * <li>"java.lang.Integer::valueOf" is a reference to static method in {@link Integer} class 316 * <li>"java.lang.Integer::valueOf" is a reference to static method in {@link Integer} class
317 * </ul> 317 * </ul>
318 * Once an symbol is obtained, it remembers values for fast acces and is ready for being 318 * Once an symbol is obtained, it remembers values for fast access and is ready for being
319 * invoked. 319 * invoked.
320 * 320 *
321 * @param globalName the name of the symbol to find 321 * @param globalName the name of the symbol to find
322 * @return found symbol or <code>null</code> if it has not been found 322 * @return found symbol or <code>null</code> if it has not been found
323 */ 323 */
389 389
390 /** 390 /**
391 * Description of a language registered in {@link TruffleVM Truffle virtual machine}. Languages 391 * Description of a language registered in {@link TruffleVM Truffle virtual machine}. Languages
392 * are registered by {@link Registration} annotation which stores necessary information into a 392 * are registered by {@link Registration} annotation which stores necessary information into a
393 * descriptor inside of the language's JAR file. When a new {@link TruffleVM} is created, it 393 * descriptor inside of the language's JAR file. When a new {@link TruffleVM} is created, it
394 * reads all available descritors and creates {@link Language} objects to represent them. One 394 * reads all available descriptors and creates {@link Language} objects to represent them. One
395 * can obtain a {@link #getName() name} or list of supported {@link #getMimeTypes() mimetypes} 395 * can obtain a {@link #getName() name} or list of supported {@link #getMimeTypes() MIME types}
396 * for each language. The actual language implementation is not initialized until 396 * for each language. The actual language implementation is not initialized until
397 * {@link TruffleVM#eval(java.lang.String, java.lang.String) a code is evaluated} in it. 397 * {@link TruffleVM#eval(java.lang.String, java.lang.String) a code is evaluated} in it.
398 */ 398 */
399 public final class Language { 399 public final class Language {
400 private final Properties props; 400 private final Properties props;
403 Language(Properties props) { 403 Language(Properties props) {
404 this.props = props; 404 this.props = props;
405 } 405 }
406 406
407 /** 407 /**
408 * Mimetypes recognized by the language. 408 * MIME types recognized by the language.
409 * 409 *
410 * @return returns immutable set of recognized mimetypes 410 * @return returns immutable set of recognized MIME types
411 */ 411 */
412 public Set<String> getMimeTypes() { 412 public Set<String> getMimeTypes() {
413 TreeSet<String> ts = new TreeSet<>(); 413 TreeSet<String> ts = new TreeSet<>();
414 for (int i = 0;; i++) { 414 for (int i = 0;; i++) {
415 String mt = props.getProperty("mimeType." + i); 415 String mt = props.getProperty("mimeType." + i);