Mercurial > hg > truffle

comparison truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/TruffleRuntime.java @ 21951:9c8c0937da41

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Moving all sources into truffle subdirectory
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Wed, 17 Jun 2015 10:58:08 +0200
parents graal/com.oracle.truffle.api/src/com/oracle/truffle/api/TruffleRuntime.java@656331a61829
children dc83cc1f94f2
comparison
equal deleted inserted replaced
21950:2a5011c7e641 21951:9c8c0937da41
1 /*
2 * Copyright (c) 2012, 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 java.util.*;
28
29 import com.oracle.truffle.api.frame.*;
30 import com.oracle.truffle.api.nodes.*;
31
32 /**
33 * Interface representing a Truffle runtime object. The runtime is responsible for creating call
34 * targets and performing optimizations for them.
35 */
36 public interface TruffleRuntime {
37
38 /**
39 * Name describing this runtime implementation for debugging purposes.
40 *
41 * @return the name as a String
42 */
43 String getName();
44
45 /**
46 * Creates a new call target for a given root node.
47 *
48 * @param rootNode the root node whose
49 * {@link RootNode#execute(com.oracle.truffle.api.frame.VirtualFrame)} method
50 * represents the entry point
51 * @return the new call target object
52 */
53 RootCallTarget createCallTarget(RootNode rootNode);
54
55 /**
56 * Creates a new runtime specific version of {@link DirectCallNode}.
57 *
58 * @param target the direct {@link CallTarget} to call
59 * @return the new call node
60 */
61 DirectCallNode createDirectCallNode(CallTarget target);
62
63 /**
64 * Experimental API. May change without notice.
65 */
66 LoopNode createLoopNode(RepeatingNode body);
67
68 /**
69 * Creates a new runtime specific version of {@link IndirectCallNode}.
70 *
71 * @return the new call node
72 */
73 IndirectCallNode createIndirectCallNode();
74
75 /**
76 * Creates a new assumption object that can be checked and invalidated.
77 *
78 * @return the newly created assumption object
79 */
80 Assumption createAssumption();
81
82 /**
83 * Creates a new assumption object with a given name that can be checked and invalidated.
84 *
85 * @param name the name for the new assumption
86 * @return the newly created assumption object
87 */
88 Assumption createAssumption(String name);
89
90 /**
91 * Creates a new virtual frame object that can be used to store values and is potentially
92 * optimizable by the runtime.
93 *
94 * @return the newly created virtual frame object
95 */
96 VirtualFrame createVirtualFrame(Object[] arguments, FrameDescriptor frameDescriptor);
97
98 /**
99 * Creates a new materialized frame object that can be used to store values.
100 *
101 * @return the newly created materialized frame object
102 */
103 MaterializedFrame createMaterializedFrame(Object[] arguments);
104
105 /**
106 * Creates a new materialized frame object with the given frame descriptor that can be used to
107 * store values.
108 *
109 * @param frameDescriptor the frame descriptor describing this frame's values
110 * @return the newly created materialized frame object
111 */
112 MaterializedFrame createMaterializedFrame(Object[] arguments, FrameDescriptor frameDescriptor);
113
114 /**
115 * Creates an object which allows you to test for support of and set options specific for this
116 * runtime.
117 *
118 * @return the newly created compiler options object
119 */
120 CompilerOptions createCompilerOptions();
121
122 /**
123 * Accesses the current stack, i.e., the contents of the {@link Frame}s and the associated
124 * {@link CallTarget}s. Iteration starts at the caller frame, i.e., it does not include the
125 * current frame.
126 *
127 * Iteration continues as long as {@link FrameInstanceVisitor#visitFrame}, which is invoked for
128 * every {@link FrameInstance}, returns null. Any non-null result of the visitor indicates that
129 * frame iteration should stop.
130 *
131 * @param visitor the visitor that is called for every matching frame.
132 * @return the last result returned by the visitor (which is non-null to indicate that iteration
133 * should stop), or null if the whole stack was iterated.
134 */
135 <T> T iterateFrames(FrameInstanceVisitor<T> visitor);
136
137 /**
138 * Accesses the caller frame. This is a convenience method that returns the first frame that is
139 * passed to the visitor of {@link #iterateFrames}.
140 */
141 FrameInstance getCallerFrame();
142
143 /**
144 * Accesses the current frame, i.e., the frame of the closest {@link CallTarget}. It is
145 * important to note that this {@link FrameInstance} supports only slow path access.
146 */
147 FrameInstance getCurrentFrame();
148
149 /**
150 * Requests a capability from the runtime.
151 *
152 * @param capability the type of the interface representing the capability
153 * @return an implementation of the capability or {@code null} if the runtime does not offer it
154 */
155 <T> T getCapability(Class<T> capability);
156
157 /**
158 * Returns a list of all still referenced {@link RootCallTarget} instances that were created
159 * using {@link #createCallTarget(RootNode)}.
160 */
161 Collection<RootCallTarget> getCallTargets();
162
163 /**
164 * Internal API method. Do not use.
165 */
166 void notifyTransferToInterpreter();
167
168 }