Mercurial > hg > graal-jvmci-8

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/TruffleLanguage.java @ 21468:99942eac9c6d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Introducing TruffleVM - a central place to invoke code in any registered TruffleLanguage.
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Fri, 22 May 2015 13:41:10 +0200
parents
children bb51b9a142b3
comparison
equal deleted inserted replaced
21467:d4db9d812c8d 21468:99942eac9c6d
1 /*
2 * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
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
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package com.oracle.truffle.api;
26
27 import com.oracle.truffle.api.impl.Accessor;
28 import com.oracle.truffle.api.source.Source;
29 import com.oracle.truffle.api.vm.TruffleVM;
30 import com.oracle.truffle.api.vm.TruffleVM.Language;
31 import java.io.IOException;
32 import java.lang.annotation.ElementType;
33 import java.lang.annotation.Retention;
34 import java.lang.annotation.RetentionPolicy;
35 import java.lang.annotation.Target;
36
37 /**
38 * An entry point for everyone who wants to implement a Truffle based language. By providing
39 * implementation of this type and registering it using {@link Registration} annotation, your
40 * language becomes accessible to users of the {@link TruffleVM Truffle virtual machine} - all they
41 * will need to do is to include your JAR into their application and all the Truffle goodies (multi
42 * language support, multi tennat hosting, debugging, etc.) will be made available to them.
43 */
44 public abstract class TruffleLanguage {
45 private Env env;
46
47 /**
48 * The annotation to use to register your language to the {@link TruffleVM Truffle} system. By
49 * annotating your implementation of {@link TruffleLanguage} by this annotation you are just a
50 * <em>one JAR drop to the classpath</em> away from your users. Once they include your JAR in
51 * their application, your language will be available to the {@link TruffleVM Truffle virtual
52 * machine}.
53 */
54 @Retention(RetentionPolicy.SOURCE)
55 @Target(ElementType.TYPE)
56 public @interface Registration {
57 /**
58 * Unique name of your language. This name will be exposed to users via the
59 * {@link Language#getName()} getter.
60 *
61 * @return identifier of your language
62 */
63 String name();
64
65 /**
66 * List of mimetypes associated with your language. Users will use them (directly or
67 * inderectly) when {@link TruffleVM#eval(java.lang.String, java.lang.String) executing}
68 * their code snippets or their {@link TruffleVM#eval(java.net.URI) files}.
69 *
70 * @return array of mime types assigned to your language files
71 */
72 String[] mimeType();
73 }
74
75 @SuppressWarnings("all")
76 void attachEnv(Env env) {
77 this.env = env;
78 }
79
80 protected final Env env() {
81 if (this.env == null) {
82 throw new NullPointerException("Accessing env before initialization is finished");
83 }
84 return this.env;
85 }
86
87 protected abstract Object eval(Source code) throws IOException;
88
89 /**
90 * Called when some other language is seeking for a global symbol. This method is supposed to do
91 * lazy binding, e.g. there is no need to export symbols in advance, it is fine to wait until
92 * somebody asks for it (by calling this method).
93 * <p>
94 * The exported object can either be <code>TruffleObject</code> (e.g. a native object from the
95 * other language) to support interoperability between languages or one of Java primitive
96 * wrappers ( {@link Integer}, {@link Double}, {@link Short}, etc.).
97 *
98 * @param globalName the name of the global symbol to find
99 * @return an exported object or <code>null</code>, if the symbol does not represent anything
100 * meaningful in this language
101 */
102 protected abstract Object findExportedSymbol(String globalName);
103
104 /**
105 * Returns global object for the language.
106 * <p>
107 * The object is expected to be <code>TruffleObject</code> (e.g. a native object from the other
108 * language) but technically it can be one of Java primitive wrappers ({@link Integer},
109 * {@link Double}, {@link Short}, etc.).
110 *
111 * @return the global object or <code>null</code> if the language does not support such concept
112 */
113 protected abstract Object getLanguageGlobal();
114
115 /**
116 * Checks whether the object is provided by this language.
117 *
118 * @param object the object to check
119 * @return <code>true</code> if this language can deal with such object in native way
120 */
121 protected abstract boolean isObjectOfLanguage(Object object);
122
123 /**
124 * Represents execution environment of the {@link TruffleLanguage}. Each active
125 * {@link TruffleLanguage} receives instance of the environment before any code is executed upon
126 * it. The environment has knowledge of all active languages and can exchange symbols between
127 * them.
128 */
129 public static final class Env {
130 private final TruffleVM vm;
131 private final TruffleLanguage lang;
132
133 Env(TruffleVM vm, TruffleLanguage lang) {
134 this.vm = vm;
135 this.lang = lang;
136 }
137
138 /**
139 * Asks the environment to go through other registered languages and find whether they
140 * export global symbol of specified name. The expected return type is either
141 * <code>TruffleObject</code>, or one of wrappers of Java primitive types ({@link Integer},
142 * {@link Double}).
143 *
144 * @param globalName the name of the symbol to search for
145 * @return object representing the symbol or <code>null</code>
146 */
147 public Object importSymbol(String globalName) {
148 return API.importSymbol(vm, lang, globalName);
149 }
150 }
151
152 private static final AccessAPI API = new AccessAPI();
153
154 private static final class AccessAPI extends Accessor {
155
156 @Override
157 protected Env attachEnv(TruffleVM vm, TruffleLanguage l) {
158 Env env = new Env(vm, l);
159 l.attachEnv(env);
160 return env;
161 }
162
163 @Override
164 public Object importSymbol(TruffleVM vm, TruffleLanguage queryingLang, String globalName) {
165 return super.importSymbol(vm, queryingLang, globalName);
166 }
167
168 @Override
169 protected Object eval(TruffleLanguage l, Source s) throws IOException {
170 return l.eval(s);
171 }
172
173 @Override
174 protected Object findExportedSymbol(TruffleLanguage l, String globalName) {
175 return l.findExportedSymbol(globalName);
176 }
177
178 @Override
179 protected Object languageGlobal(TruffleLanguage l) {
180 return l.getLanguageGlobal();
181 }
182 }
183 }