Mercurial > hg > graal-compiler

comparison graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/Message.java @ 21770:c76742cc2c6f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Mon, 08 Jun 2015 04:50:13 +0200
parents
children
comparison
equal deleted inserted replaced
21769:b6309a7d5a44 21770:c76742cc2c6f
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.interop;
26
27 import com.oracle.truffle.api.nodes.Node;
28 import com.oracle.truffle.api.interop.ForeignAccess.Factory;
29
30 /**
31 * Inter-operability is based on sending messages. Standard messages are defined as as constants
32 * like {@link #IS_NULL} or factory methods in this class, but one can always define their own,
33 * specialized messages.
34 */
35 public abstract class Message {
36 /**
37 * Message to read a field.
38 */
39 public static final Message READ = Read.INSTANCE;
40
41 /**
42 * Converts {@link TruffleObject truffle value} to Java primitive type. Primitive types are
43 * subclasses of {@link Number}, {@link Boolean}, {@link Character} and {@link String}. Related
44 * to {@link #IS_BOXED} message.
45 */
46 public static final Message UNBOX = Unbox.INSTANCE;
47
48 /**
49 * Message to write a field.
50 */
51 public static Message WRITE = Write.INSTANCE;
52
53 /**
54 * Creates an execute message. All messages created by this method are
55 * {@link Object#equals(java.lang.Object) equal} to each other regardless of the value of
56 * <code>argumentsLength</code>.
57 *
58 * @param argumentsLength number of parameters to pass to the target
59 * @return execute message
60 */
61 public static Message createExecute(int argumentsLength) {
62 return Execute.create(false, argumentsLength);
63 }
64
65 /**
66 * Message to check for executability.
67 * <p>
68 * Calling {@link Factory#access(com.oracle.truffle.api.interop.Message) the target} created for
69 * this message should yield value of {@link Boolean}.
70 */
71 public static final Message IS_EXECUTABLE = IsExecutable.INSTANCE;
72
73 /**
74 * Creates an execute message. All messages created by this method are
75 * {@link Object#equals(java.lang.Object) equal} to each other regardless of the value of
76 * <code>argumentsLength</code>. The expected behavior of this message is to perform
77 * {@link #READ} first and on the result invoke {@link #createExecute(int)}.
78 *
79 * @param argumentsLength number of parameters to pass to the target
80 * @return read & execute message
81 */
82 public static Message createInvoke(int argumentsLength) {
83 return Execute.create(true, argumentsLength);
84 }
85
86 /**
87 * Check for <code>null</code> message. The Truffle languages are suggested to have their own
88 * object representing <code>null</code> like values in their languages. For purposes of
89 * inter-operability it is essential to canonicalize such values from time to time - sending
90 * this message is a way to recognize such <code>null</code> representing values.
91 * <p>
92 * Calling {@link Factory#access(com.oracle.truffle.api.interop.Message) the target} created for
93 * this message should yield value of {@link Boolean}.
94 */
95 public static final Message IS_NULL = IsNull.INSTANCE;
96
97 /**
98 * Message to check for having a size.
99 * <p>
100 * Calling {@link Factory#access(com.oracle.truffle.api.interop.Message) the target} created for
101 * this message should yield value of {@link Boolean}.
102 */
103 public static final Message HAS_SIZE = HasSize.INSTANCE;
104
105 /**
106 * Getter of the size. If {@link #HAS_SIZE supported}, this message allows to obtain a size (of
107 * an array).
108 * <p>
109 * Calling {@link Factory#access(com.oracle.truffle.api.interop.Message) the target} created for
110 * this message should yield value of {@link Integer}.
111 */
112 public static final Message GET_SIZE = GetSize.INSTANCE;
113
114 /**
115 * Check for value being boxed. Can you value be converted to one of the basic Java types? Many
116 * languages have a special representation for types like number, string, etc. To ensure
117 * inter-operability, these types should support unboxing - if they do, they should handle this
118 * message.
119 * <p>
120 * Calling {@link Factory#accessMessage(com.oracle.truffle.api.interop.Message) the target}
121 * created for this message should yield value of {@link Boolean}.
122 */
123 public static final Message IS_BOXED = IsBoxed.INSTANCE;
124
125 /**
126 * Compares types of two messages. Messages are encouraged to implement this method. All
127 * standard ones ({@link #IS_NULL}, {@link #READ}, etc.) do so. Messages obtained via the same
128 * {@link #createExecute(int) method} are equal, messages obtained by different methods or
129 * fields are not.
130 *
131 * @param message the object to compare to
132 * @return true, if the structure of the message is that same as of <code>this</code> one.
133 */
134 @Override
135 public abstract boolean equals(Object message);
136
137 /**
138 * When re-implementing {@link #equals(java.lang.Object)}, it is generally recommended to also
139 * implement <code>hashCode()</code>.
140 *
141 * @return hash code
142 */
143 @Override
144 public abstract int hashCode();
145
146 /**
147 * Creates an AST node for this message. The node can be inserted into AST of your language and
148 * will handle communication with the foreign language.
149 *
150 * @return node to be inserted into your AST and passed back to
151 * {@link ForeignAccess#execute(com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.VirtualFrame, com.oracle.truffle.api.interop.TruffleObject, java.lang.Object[])}
152 * method.
153 */
154 public final Node createNode() {
155 return new ForeignObjectAccessHeadNode(this);
156 }
157
158 }