Mercurial > hg > truffle

annotate truffle/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/Message.java @ 22108:f84a7663966d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Wed, 26 Aug 2015 12:51:55 +0200
parents 3b2ae36a942f
children e70b20f4bb00
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
1 /*
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
2 * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
4 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
5 * This code is free software; you can redistribute it and/or modify it
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
6 * under the terms of the GNU General Public License version 2 only, as
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
7 * published by the Free Software Foundation. Oracle designates this
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
8 * particular file as subject to the "Classpath" exception as provided
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
9 * by Oracle in the LICENSE file that accompanied this code.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
10 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
11 * This code is distributed in the hope that it will be useful, but WITHOUT
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
14 * version 2 for more details (a copy is included in the LICENSE file that
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
15 * accompanied this code).
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
16 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
17 * You should have received a copy of the GNU General Public License version
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
18 * 2 along with this work; if not, write to the Free Software Foundation,
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
20 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
22 * or visit www.oracle.com if you need additional information or have any
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
23 * questions.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
24 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
25 package com.oracle.truffle.api.interop;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
26
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
27 import com.oracle.truffle.api.nodes.Node;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
28 import com.oracle.truffle.api.interop.ForeignAccess.Factory;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
29
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
30 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
31 * Inter-operability is based on sending messages. Standard messages are defined as as constants
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
32 * like {@link #IS_NULL} or factory methods in this class, but one can always define their own,
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
33 * specialized messages.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
34 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
35 public abstract class Message {
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
36 /**
22106
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
37 * Message to read an object field. The
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
38 * {@link Factory#access(com.oracle.truffle.api.interop.Message) target} created for this
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
39 * message accepts single {@link ForeignAccess#getArguments(com.oracle.truffle.api.frame.Frame)
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
40 * argument} identifying a field to read - e.g. either {@link String} or an {@link Integer} - if
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
41 * access to an array at particular index is requested.
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
42 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
43 public static final Message READ = Read.INSTANCE;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
44
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
45 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
46 * Converts {@link TruffleObject truffle value} to Java primitive type. Primitive types are
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
47 * subclasses of {@link Number}, {@link Boolean}, {@link Character} and {@link String}. Related
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
48 * to {@link #IS_BOXED} message.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
49 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
50 public static final Message UNBOX = Unbox.INSTANCE;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
51
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
52 /**
22106
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
53 * Message to write a field. The {@link Factory#access(com.oracle.truffle.api.interop.Message)
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
54 * target} created for this message accepts two
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
55 * {@link ForeignAccess#getArguments(com.oracle.truffle.api.frame.Frame) arguments}. The first
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
56 * one identifies a field to read - e.g. either {@link String} or an {@link Integer} - if access
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
57 * to an array at particular index is requested. The second one is the value to assign to such
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
58 * field.
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
59 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
60 public static Message WRITE = Write.INSTANCE;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
61
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
62 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
63 * Creates an execute message. All messages created by this method are
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
64 * {@link Object#equals(java.lang.Object) equal} to each other regardless of the value of
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
65 * <code>argumentsLength</code>.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
66 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
67 * @param argumentsLength number of parameters to pass to the target
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
68 * @return execute message
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
69 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
70 public static Message createExecute(int argumentsLength) {
22108
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
71 return Execute.create(Execute.EXECUTE, argumentsLength);
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
72 }
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
73
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
74 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
75 * Message to check for executability.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
76 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
77 * Calling {@link Factory#access(com.oracle.truffle.api.interop.Message) the target} created for
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
78 * this message should yield value of {@link Boolean}.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
79 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
80 public static final Message IS_EXECUTABLE = IsExecutable.INSTANCE;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
81
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
82 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
83 * Creates an execute message. All messages created by this method are
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
84 * {@link Object#equals(java.lang.Object) equal} to each other regardless of the value of
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
85 * <code>argumentsLength</code>. The expected behavior of this message is to perform
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
86 * {@link #READ} first and on the result invoke {@link #createExecute(int)}.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
87 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
88 * @param argumentsLength number of parameters to pass to the target
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
89 * @return read & execute message
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
90 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
91 public static Message createInvoke(int argumentsLength) {
22108
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
92 return Execute.create(Execute.INVOKE, argumentsLength);
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
93 }
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
94
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
95 /**
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
96 * Creates an allocation message. All messages created by this method are
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
97 * {@link Object#equals(java.lang.Object) equal} to each other regardless of the value of
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
98 * <code>argumentsLength</code>. The expected behavior of this message is to allocate a new
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
99 * instance of the {@link ForeignAccess#getReceiver(com.oracle.truffle.api.frame.Frame)
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
100 * receiver} and then perform its constructor with appropriate number of arguments.
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
101 *
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
102 * @param argumentsLength number of parameters to pass to the target
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
103 * @return read & execute message
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
104 */
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
105 public static Message createNew(int argumentsLength) {
f84a7663966d Adding Message.createNew into standard interop messages so languages like Ruby and Java can use 'new' to instantiate Java classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22106
diff changeset
106 return Execute.create(Execute.NEW, argumentsLength);
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
107 }
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
108
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
109 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
110 * Check for <code>null</code> message. The Truffle languages are suggested to have their own
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
111 * object representing <code>null</code> like values in their languages. For purposes of
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
112 * inter-operability it is essential to canonicalize such values from time to time - sending
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
113 * this message is a way to recognize such <code>null</code> representing values.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
114 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
115 * Calling {@link Factory#access(com.oracle.truffle.api.interop.Message) the target} created for
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
116 * this message should yield value of {@link Boolean}.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
117 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
118 public static final Message IS_NULL = IsNull.INSTANCE;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
119
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
120 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
121 * Message to check for having a size.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
122 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
123 * Calling {@link Factory#access(com.oracle.truffle.api.interop.Message) the target} created for
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
124 * this message should yield value of {@link Boolean}.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
125 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
126 public static final Message HAS_SIZE = HasSize.INSTANCE;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
127
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
128 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
129 * Getter of the size. If {@link #HAS_SIZE supported}, this message allows to obtain a size (of
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
130 * an array).
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
131 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
132 * Calling {@link Factory#access(com.oracle.truffle.api.interop.Message) the target} created for
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
133 * this message should yield value of {@link Integer}.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
134 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
135 public static final Message GET_SIZE = GetSize.INSTANCE;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
136
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
137 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
138 * Check for value being boxed. Can you value be converted to one of the basic Java types? Many
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
139 * languages have a special representation for types like number, string, etc. To ensure
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
140 * inter-operability, these types should support unboxing - if they do, they should handle this
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
141 * message.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
142 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
143 * Calling {@link Factory#accessMessage(com.oracle.truffle.api.interop.Message) the target}
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
144 * created for this message should yield value of {@link Boolean}.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
145 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
146 public static final Message IS_BOXED = IsBoxed.INSTANCE;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
147
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
148 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
149 * Compares types of two messages. Messages are encouraged to implement this method. All
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
150 * standard ones ({@link #IS_NULL}, {@link #READ}, etc.) do so. Messages obtained via the same
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
151 * {@link #createExecute(int) method} are equal, messages obtained by different methods or
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
152 * fields are not.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
153 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
154 * @param message the object to compare to
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
155 * @return true, if the structure of the message is that same as of <code>this</code> one.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
156 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
157 @Override
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
158 public abstract boolean equals(Object message);
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
159
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
160 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
161 * When re-implementing {@link #equals(java.lang.Object)}, it is generally recommended to also
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
162 * implement <code>hashCode()</code>.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
163 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
164 * @return hash code
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
165 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
166 @Override
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
167 public abstract int hashCode();
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
168
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
169 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
170 * Creates an AST node for this message. The node can be inserted into AST of your language and
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
171 * will handle communication with the foreign language.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
172 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
173 * @return node to be inserted into your AST and passed back to
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
174 * {@link ForeignAccess#execute(com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.VirtualFrame, com.oracle.truffle.api.interop.TruffleObject, java.lang.Object[])}
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
175 * method.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
176 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
177 public final Node createNode() {
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
178 return new ForeignObjectAccessHeadNode(this);
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
179 }
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
180
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
181 }