Mercurial > hg > truffle

annotate truffle/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/Message.java @ 22157:dc83cc1f94f2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Using fully qualified imports
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Wed, 16 Sep 2015 11:33:22 +0200
parents 48004d27086d
children 6af6ca6c848e
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
22154
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
27 import com.oracle.truffle.api.TruffleLanguage.Env;
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
28 import com.oracle.truffle.api.frame.VirtualFrame;
22157
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22155
diff changeset
29 import com.oracle.truffle.api.interop.ForeignAccess.Factory;
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
30 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
31
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
32 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
33 * 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
34 * 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
35 * specialized messages.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
36 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
37 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
38 /**
22155
48004d27086d Documenting the rules for subclasses
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22154
diff changeset
39 * One can define their own extended message by subclassing. The expectation is that the
48004d27086d Documenting the rules for subclasses
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22154
diff changeset
40 * subclass will have public constructor and its {@link #equals(java.lang.Object)} and
48004d27086d Documenting the rules for subclasses
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22154
diff changeset
41 * {@link #hashCode()} methods will operate on the class equivalence. Only then the subclass
48004d27086d Documenting the rules for subclasses
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22154
diff changeset
42 * will work properly with {@link #valueOf(java.lang.String)} and
48004d27086d Documenting the rules for subclasses
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22154
diff changeset
43 * {@link #toString(com.oracle.truffle.api.interop.Message)} methods.
48004d27086d Documenting the rules for subclasses
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22154
diff changeset
44 */
48004d27086d Documenting the rules for subclasses
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22154
diff changeset
45 protected Message() {
48004d27086d Documenting the rules for subclasses
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22154
diff changeset
46 }
48004d27086d Documenting the rules for subclasses
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22154
diff changeset
47
48004d27086d Documenting the rules for subclasses
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22154
diff changeset
48 /**
22106
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
49 * 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
50 * {@link Factory#access(com.oracle.truffle.api.interop.Message) target} created for this
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
51 * message accepts (in addition to a
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
52 * {@link ForeignAccess#getReceiver(com.oracle.truffle.api.frame.Frame) receiver}) a single
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
53 * {@link ForeignAccess#getArguments(com.oracle.truffle.api.frame.Frame) argument} identifying a
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
54 * field to read - e.g. either {@link String} or an {@link Integer} - if access to an array at
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
55 * particular index is requested. The code that wants to send this message should use:
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
56 *
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
57 * <pre>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
58 * {@link ForeignAccess}.{@link ForeignAccess#execute(com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.VirtualFrame, com.oracle.truffle.api.interop.TruffleObject, java.lang.Object...) execute}(
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
59 * {@link Message#READ}.{@link Message#createNode()}, {@link VirtualFrame currentFrame}, receiver, nameOfTheField
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
60 * );
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
61 * </pre>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
62 *
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
63 * Where <code>receiver</code> is the {@link TruffleObject foreign object} to access and
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
64 * <code>nameOfTheField</code> is the name (or index) of its field.
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
65 * <p>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
66 * To achieve good performance it is essential to cache/keep reference to the
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
67 * {@link Message#createNode() created node}.
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
68 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
69 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
70
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
71 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
72 * Converts {@link TruffleObject truffle value} to Java primitive type. Primitive types are
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
73 * subclasses of {@link Number}, {@link Boolean}, {@link Character} and {@link String}. Before
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
74 * sending the {@link #UNBOX} message, it is desirable to send the {@link #IS_BOXED} one and
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
75 * verify that the object can really be unboxed. To unbox an object, use:
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
76 *
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
77 * <pre>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
78 * {@link ForeignAccess}.{@link ForeignAccess#execute(com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.VirtualFrame, com.oracle.truffle.api.interop.TruffleObject, java.lang.Object...) execute}(
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
79 * {@link Message#UNBOX}.{@link Message#createNode()}, {@link VirtualFrame currentFrame}, objectToUnbox
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
80 * );
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
81 * </pre>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
82 *
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
83 * The returned value should be subclass of {@link Number}, {@link Boolean}, {@link Character}
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
84 * or {@link String}.
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
85 * <p>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
86 * To achieve good performance it is essential to cache/keep reference to the
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
87 * {@link Message#createNode() created node}.
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
88 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
89 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
90
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
91 /**
22106
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
92 * Message to write a field. The {@link Factory#access(com.oracle.truffle.api.interop.Message)
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
93 * target} created for this message accepts the object to modify as a
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
94 * {@link ForeignAccess#getReceiver(com.oracle.truffle.api.frame.Frame) receiver} and two
22106
3b2ae36a942f Improving documentation of READ and WRITE Message
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
95 * {@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
96 * 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
97 * to an array at particular index is requested. The second one is the value to assign to such
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
98 * field. Use following style to construct field modification message:
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
99 *
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
100 * <pre>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
101 * {@link ForeignAccess}.{@link ForeignAccess#execute(com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.VirtualFrame, com.oracle.truffle.api.interop.TruffleObject, java.lang.Object...) execute}(
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
102 * {@link Message#WRITE}.{@link Message#createNode()}, {@link VirtualFrame currentFrame}, receiver, nameOfTheField, newValue
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
103 * );
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
104 * </pre>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
105 *
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
106 * Where <code>receiver</code> is the {@link TruffleObject foreign object} to access,
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
107 * <code>nameOfTheField</code> is the name (or index) of its field and <code>newValue</code> is
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
108 * the value to assign to the receiver's field.
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
109 * <p>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
110 * To achieve good performance it is essential to cache/keep reference to the
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
111 * {@link Message#createNode() created node}.
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
112 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
113 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
114
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
115 /**
22154
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
116 * Creates a non-object oriented execution message. In contrast to {@link #createInvoke(int)}
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
117 * messages, which are more suitable for dealing with object oriented style of programming,
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
118 * messages created by this method are more suitable for execution where one can explicitly
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
119 * control all passed in arguments.
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
120 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
121 * To inter-operate with a non-OOP language like <em>C</em> - for example to execute its
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
122 * function:
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
123 *
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
124 * <pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
125 * <b>double</b> add(<b>double</b> a, <b>double</b> b) {
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
126 * <b>return</b> a + b;
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
127 * }
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
128 * </pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
129 *
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
130 * One can obtain reference to the <em>add</em> function (for example by
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
131 * {@link Env#importSymbol(java.lang.String) importing it as a global symbol}) and store it into
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
132 * variable <code>addFunction</code>. Then it's time to check the object is executable by
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
133 * sending it the {@link #IS_EXECUTABLE} message. If the answer is <code>true</code> one can:
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
134 *
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
135 * <pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
136 * {@link ForeignAccess}.{@link ForeignAccess#execute(com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.VirtualFrame, com.oracle.truffle.api.interop.TruffleObject, java.lang.Object...) execute}(
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
137 * {@link Message#createExecute(int) Message.createExecute}(2).{@link Message#createNode()}, {@link VirtualFrame currentFrame}, addFunction, valueOfA, valueOfB
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
138 * );
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
139 * </pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
140 *
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
141 * The <code>valueOfA</code> and <code>valueOfB</code> should be <code>double</code> or
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
142 * {@link Double} or at least be {@link #UNBOX unboxable} to such type.
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
143 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
144 * One can use this method to talk to object oriented language as well, however one needs to pay
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
145 * attention to provide all necessary arguments manually - usually an OOP language requires the
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
146 * first argument to represent <code>this</code> or <code>self</code> and only then pass in the
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
147 * additional arguments. It may be easier to use {@link #createInvoke(int)} message which is
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
148 * more suitable for object oriented languages and handles (if supported) the arguments
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
149 * manipulation automatically.
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
150 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
151 *
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
152 *
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
153 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
154 * All messages created by this method are {@link Object#equals(java.lang.Object) equal} to each
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
155 * other regardless of the value of <code>argumentsLength</code>.
21770
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 * @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
158 * @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
159 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
160 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
161 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
162 }
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 /**
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
165 * Message to check executability of a
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
166 * {@link ForeignAccess#getReceiver(com.oracle.truffle.api.frame.Frame) foreign object}.
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
167 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
168 * Calling {@link Factory#access(com.oracle.truffle.api.interop.Message) the target} created for
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
169 * this message accepts {@link ForeignAccess#getArguments(com.oracle.truffle.api.frame.Frame) no
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
170 * arguments} and a single non-null
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
171 * {@link ForeignAccess#getReceiver(com.oracle.truffle.api.frame.Frame) receiver}. The call
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
172 * should yield value of {@link Boolean}. Either {@link Boolean#TRUE} if the receiver can be
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
173 * executed (e.g. accepts {@link #createExecute(int)} message, or {@link Boolean#FALSE}
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
174 * otherwise. This is the way to send the <code>IS_EXECUTABLE</code> message:
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
175 *
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
176 * <pre>
22149
b84a11723d64 Shortening some too-long lines checkstyle complains about.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22147
diff changeset
177 * {@link Boolean} canBeExecuted = ({@link Boolean}) {@link ForeignAccess}.execute(
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
178 * {@link Message#IS_EXECUTABLE}.{@link Message#createNode()}, {@link VirtualFrame currentFrame}, receiver
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
179 * );
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
180 * </pre>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
181 * <p>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
182 * To achieve good performance it is essential to cache/keep reference to the
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
183 * {@link Message#createNode() created node}.
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
184 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
185 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
186
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
187 /**
22154
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
188 * Creates an object oriented execute message. Unlike {@link #createExecute(int)} the receiver
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
189 * of the message isn't the actual function to invoke, but an object. The object has the
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
190 * function as a field, or as a field of its class, or whatever is appropriate for an object
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
191 * oriented language.
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
192 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
193 * Languages that don't support object oriented semantics do not and should not implement this
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
194 * message. When the invoke message isn't supported, the caller is expected to fall back into
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
195 * following basic operations:
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
196 * <ul>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
197 * <li>sending {@link #READ} message to access the field</li>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
198 * <li>verify the result {@link #IS_EXECUTABLE}, if so continue by</li>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
199 * <li>sending {@link #createExecute(int) execute message}</li>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
200 * </ul>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
201 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
202 * The last step is problematic, as it is not clear whether to pass just the execution
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
203 * arguments, or prefix them with the original receiver (aka <code>this</code> or
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
204 * <code>self</code>). Object oriented languages would in general welcome obtaining the
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
205 * receiving object as first argument, non-object languages like <em>C</em> would get confused
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
206 * by doing so. However it is not possible for the caller to find out what language one is
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
207 * sending message to - only the set of supported messages is known. As a result it is
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
208 * recommended for object oriented languages to support the {@link #createInvoke(int)} message
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
209 * and handle the semantics the way it is natural to them. Languages like <em>C</em> shouldn't
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
210 * implement {@link #createInvoke(int)} and just support primitive operations like
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
211 * {@link #createExecute(int)} and {@link #READ}.
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
212 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
213 * When accessing a method of an object in an object oriented manner, one is supposed to send
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
214 * the {@link #createInvoke(int)} message first. Only when that fails, fallback to non-object
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
215 * oriented workflow with {@link #createExecute(int)}. Imagine there is a <em>Java</em> class
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
216 * with <code>add</code> method and its instance:
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
217 *
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
218 * <pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
219 * <b>public class</b> Arith {
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
220 * <b>public double</b> add(double a, double b) {
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
221 * <b>return</b> a + b;
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
222 * }
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
223 * }
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
224 * Arith obj = <b>new</b> Arith();
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
225 * </pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
226 *
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
227 * To access <code>obj</code>'s <code>add</code> method one should use:
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
228 *
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
229 * <pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
230 * <b>try</b> {
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
231 * {@link ForeignAccess}.{@link ForeignAccess#execute(com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.VirtualFrame, com.oracle.truffle.api.interop.TruffleObject, java.lang.Object...) execute}(
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
232 * {@link Message#createInvoke(int) Message.createInvoke}(2).{@link Message#createNode()}, {@link VirtualFrame currentFrame}, obj, "add", valueOfA, valueOfB
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
233 * );
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
234 * } <b>catch</b> ({@link IllegalArgumentException} ex) {
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
235 * // access the language via {@link #createExecute(int)}
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
236 * }
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
237 * </pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
238 *
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
239 * The <code>valueOfA</code> and <code>valueOfB</code> should be <code>double</code> or
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
240 * {@link Double} or at least be {@link #UNBOX unboxable} to such type.
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
241 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
242 * All messages created by this method are {@link Object#equals(java.lang.Object) equal} to each
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
243 * other regardless of the value of <code>argumentsLength</code>. The expected behavior of this
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
244 * message is to perform {@link #READ} first and on the result invoke
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
245 * {@link #createExecute(int)}.
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
246 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
247 * @param argumentsLength number of parameters to pass to the target
22154
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
248 * @return message combining read & execute messages tailored for use with object oriented
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
249 * languages
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
250 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
251 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
252 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
253 }
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
254
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
255 /**
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
256 * 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
257 * {@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
258 * <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
259 * 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
260 * 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
261 *
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
262 * @param argumentsLength number of parameters to pass to the target
22154
cc195dd45121 Describing difference between createExecute and createInvoke messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22149
diff changeset
263 * @return new instance message
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
264 */
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
265 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
266 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
267 }
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
268
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
269 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
270 * 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
271 * 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
272 * inter-operability it is essential to canonicalize such values from time to time - sending
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
273 * this message is a way to recognize such <code>null</code> representing values:
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
274 *
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
275 * <pre>
22149
b84a11723d64 Shortening some too-long lines checkstyle complains about.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22147
diff changeset
276 * {@link Boolean} isNull = ({@link Boolean}) {@link ForeignAccess}.execute(
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
277 * {@link Message#IS_NULL}.{@link Message#createNode()}, {@link VirtualFrame currentFrame}, objectToCheckForNull
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
278 * );
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
279 * </pre>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
280 *
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
281 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
282 * 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
283 * this message should yield value of {@link Boolean}.
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
284 * <p>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
285 * To achieve good performance it is essential to cache/keep reference to the
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
286 * {@link Message#createNode() created node}.
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
287 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
288 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
289
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
290 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
291 * 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
292 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
293 * 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
294 * 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
295 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
296 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
297
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
298 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
299 * 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
300 * an array).
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
301 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
302 * 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
303 * 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
304 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
305 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
306
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
307 /**
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
308 * Check for value being boxed. Can the {@link TruffleObject foreign object} be converted to one
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
309 * of the basic Java types? Many languages have a special representation for types like number,
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
310 * string, etc. To ensure inter-operability, these types should support unboxing - if they do,
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
311 * they should handle this message and return {@link Boolean#TRUE}. The way to check whether an
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
312 * object is boxed is:
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
313 *
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
314 * <pre>
22149
b84a11723d64 Shortening some too-long lines checkstyle complains about.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22147
diff changeset
315 * {@link Boolean} isBoxed = ({@link Boolean}) {@link ForeignAccess}.execute(
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
316 * {@link Message#IS_BOXED}.{@link Message#createNode()}, {@link VirtualFrame currentFrame}, objectToCheck
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
317 * );
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
318 * </pre>
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
319 *
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
320 * Calling {@link Factory#accessMessage(com.oracle.truffle.api.interop.Message) the target}
22147
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
321 * created for this message should yield value of {@link Boolean}. If the object responds with
5857f5ee9486 More precise description of inter-operability messages and examples of their usage. Step #1 - e.g. the trivial messages.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22135
diff changeset
322 * {@link Boolean#TRUE}, it is safe to continue by sending it {@link #UNBOX} message.
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
323 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
324 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
325
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
326 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
327 * 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
328 * 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
329 * {@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
330 * 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
331 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
332 * @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
333 * @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
334 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
335 @Override
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
336 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
337
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
338 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
339 * 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
340 * 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
341 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
342 * @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
343 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
344 @Override
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
345 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
346
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
347 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
348 * 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
349 * 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
350 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
351 * @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
352 * {@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
353 * method.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
354 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
355 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
356 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
357 }
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
358
22135
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
359 /**
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
360 * Converts the message into canonical string representation. The converted string can be
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
361 * stored, persisted, transfered and later passed to {@link #valueOf(java.lang.String)} to
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
362 * construct the message again.
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
363 *
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
364 * @param message the message to convert
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
365 * @return canonical string representation
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
366 */
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
367 public static String toString(Message message) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
368 if (Message.READ == message) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
369 return "READ"; // NOI18N
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
370 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
371 if (Message.WRITE == message) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
372 return "WRITE"; // NOI18N
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
373 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
374 if (Message.UNBOX == message) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
375 return "UNBOX"; // NOI18N
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
376 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
377 if (Message.GET_SIZE == message) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
378 return "GET_SIZE"; // NOI18N
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
379 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
380 if (Message.HAS_SIZE == message) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
381 return "HAS_SIZE"; // NOI18N
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
382 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
383 if (Message.IS_NULL == message) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
384 return "IS_NULL"; // NOI18N
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
385 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
386 if (Message.IS_BOXED == message) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
387 return "IS_BOXED"; // NOI18N
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
388 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
389 if (Message.IS_EXECUTABLE == message) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
390 return "IS_EXECUTABLE"; // NOI18N
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
391 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
392 if (message instanceof Execute) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
393 return ((Execute) message).name();
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
394 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
395 return message.getClass().getName();
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
396 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
397
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
398 /**
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
399 * Converts string representation into real message. If the string was obtained by
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
400 * {@link #toString(com.oracle.truffle.api.interop.Message)} method, it is guaranteed to be
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
401 * successfully recognized (if the classpath of the system remains the same).
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
402 *
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
403 * @param message canonical string representation of a message
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
404 * @return the message
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
405 * @throws IllegalArgumentException if the string does not represent known message
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
406 */
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
407 public static Message valueOf(String message) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
408 try {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
409 return (Message) Message.class.getField(message).get(null);
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
410 } catch (Exception ex) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
411 try {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
412 String factory = "create" + message.charAt(0) + message.substring(1).toLowerCase();
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
413 return (Message) Message.class.getMethod(factory, int.class).invoke(null, 0);
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
414 } catch (Exception ex2) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
415 try {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
416 return (Message) Class.forName(message).newInstance();
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
417 } catch (Exception ex1) {
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
418 throw new IllegalArgumentException("Cannot find message for " + message, ex);
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
419 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
420 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
421 }
e70b20f4bb00 Implementing API for Java/Truffle interop. Based around JavaInterop.asJavaObject and JavaInterop.asTruffleObject methods. Connected to TruffleVM via Symbol.as(Class) wrapper. Verified by extended TCK.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22108
diff changeset
422 }
21770
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents:
diff changeset
423 }