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

annotate truffle/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/Message.java @ 22154:cc195dd45121

Describing difference between createExecute and createInvoke messages.

author	Jaroslav Tulach <jaroslav.tulach@oracle.com>
date	Tue, 15 Sep 2015 09:22:09 +0200
parents	b84a11723d64
children	48004d27086d

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;
21770 c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	29 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	30 import com.oracle.truffle.api.interop.ForeignAccess.Factory;
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	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 /**
22106 3b2ae36a942f Improving documentation of READ and WRITE Message Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21951 diff changeset	39 * 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	40 * {@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	41 * 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	42 * {@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	43 * {@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	44 * 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	45 * 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	46 *
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	47 * <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	48 * {@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	49 * {@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	50 * );
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 * </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	52 *
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 * 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	54 * <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	55 * <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	56 * 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	57 * {@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	58 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	59 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	60
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	61 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	62 * 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	63 * 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	64 * 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	65 * 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	66 *
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 * <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	68 * {@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	69 * {@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	70 * );
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	71 * </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	72 *
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 * 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	74 * 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	75 * <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	76 * 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	77 * {@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	78 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	79 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	80
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	81 /**
22106 3b2ae36a942f Improving documentation of READ and WRITE Message Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 21951 diff changeset	82 * 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	83 * 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	84 * {@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	85 * {@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	86 * 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	87 * 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	88 * 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	89 *
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	90 * <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	91 * {@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	92 * {@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	93 * );
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 * </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	95 *
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	96 * 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	97 * <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	98 * 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	99 * <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	100 * 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	101 * {@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	102 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	103 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	104
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	105 /**
22154 cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	106 * 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	107 * 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	108 * 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	109 * control all passed in arguments.
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	110 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	111 * 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	112 * function:
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	113 *
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	114 * <pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	115 * <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	116 * <b>return</b> a + b;
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	117 * }
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	118 * </pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	119 *
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	120 * 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	121 * {@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	122 * 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	123 * 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	124 *
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	125 * <pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	126 * {@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	127 * {@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	128 * );
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	129 * </pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	130 *
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	131 * 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	132 * {@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	133 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	134 * 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	135 * 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	136 * 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	137 * 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	138 * 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	139 * manipulation automatically.
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	140 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	141 *
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	142 *
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 * 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	145 * 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	146 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	147 * @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	148 * @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	149 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	150 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	151 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	152 }
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	153
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	154 /**
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	155 * 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	156 * {@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	157 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	158 * 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	159 * 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	160 * 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	161 * {@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	162 * 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	163 * 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	164 * 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	165 *
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 * <pre>
22149 b84a11723d64 Shortening some too-long lines checkstyle complains about. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22147 diff changeset	167 * {@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	168 * {@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	169 * );
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 * </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	171 * <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	172 * 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	173 * {@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	174 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	175 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	176
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	177 /**
22154 cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	178 * 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	179 * 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	180 * 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	181 * oriented language.
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	182 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	183 * 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	184 * 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	185 * following basic operations:
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	186 * <ul>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	187 * <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	188 * <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	189 * <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	190 * </ul>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	191 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	192 * 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	193 * 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	194 * <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	195 * 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	196 * 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	197 * 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	198 * 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	199 * 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	200 * 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	201 * {@link #createExecute(int)} and {@link #READ}.
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	202 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	203 * 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	204 * 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	205 * 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	206 * 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	207 *
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	208 * <pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	209 * <b>public class</b> Arith {
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	210 * <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	211 * <b>return</b> a + b;
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	212 * }
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	213 * }
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	214 * Arith obj = <b>new</b> Arith();
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	215 * </pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	216 *
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	217 * 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	218 *
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	219 * <pre>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	220 * <b>try</b> {
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	221 * {@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	222 * {@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	223 * );
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	224 * } <b>catch</b> ({@link IllegalArgumentException} ex) {
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	225 * // 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	226 * }
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	227 * </pre>
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 * 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	230 * {@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	231 * <p>
cc195dd45121 Describing difference between createExecute and createInvoke messages. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22149 diff changeset	232 * 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	233 * 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	234 * 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	235 * {@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	236 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	237 * @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	238 * @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	239 * languages
21770 c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	240 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	241 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	242 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	243 }
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	244
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	245 /**
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	246 * 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	247 * {@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	248 * <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	249 * 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	250 * 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	251 *
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 * @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	253 * @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	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 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	256 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	257 }
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	258
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	259 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	260 * 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	261 * 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	262 * 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	263 * 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	264 *
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	265 * <pre>
22149 b84a11723d64 Shortening some too-long lines checkstyle complains about. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22147 diff changeset	266 * {@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	267 * {@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	268 * );
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	269 * </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	270 *
21770 c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	271 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	272 * 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	273 * 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	274 * <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	275 * 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	276 * {@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	277 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	278 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	279
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	280 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	281 * 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	282 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	283 * 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	284 * 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	285 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	286 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	287
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	288 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	289 * 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	290 * an array).
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	291 * <p>
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	292 * 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	293 * 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	294 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	295 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	296
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	297 /**
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	298 * 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	299 * 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	300 * 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	301 * 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	302 * 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	303 *
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	304 * <pre>
22149 b84a11723d64 Shortening some too-long lines checkstyle complains about. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: 22147 diff changeset	305 * {@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	306 * {@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	307 * );
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 * </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	309 *
21770 c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	310 * 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	311 * 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	312 * {@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	313 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	314 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	315
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	316 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	317 * 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	318 * 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	319 * {@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	320 * 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	321 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	322 * @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	323 * @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	324 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	325 @Override
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	326 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	327
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	328 /**
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	329 * 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	330 * 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	331 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	332 * @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	333 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	334 @Override
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	335 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	336
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 * 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	339 * 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	340 *
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	341 * @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	342 * {@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	343 * method.
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	344 */
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	345 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	346 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	347 }
c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	348
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	349 /**
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	350 * 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	351 * 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	352 * 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	353 *
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	354 * @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	355 * @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	356 */
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	357 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	358 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	359 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	360 }
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 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	362 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	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 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	365 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	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 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	368 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	369 }
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 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	371 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	372 }
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 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	374 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	375 }
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 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	377 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	378 }
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 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	380 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	381 }
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 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	383 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	384 }
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 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	386 }
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
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 * 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	390 * {@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	391 * 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	392 *
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 * @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	394 * @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	395 * @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	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 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	398 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	399 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	400 } 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	401 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	402 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	403 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	404 } 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	405 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	406 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	407 } 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	408 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	409 }
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 }
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 }
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 }
21770 c76742cc2c6f Polishing inter-operability APIs: Exposing only Message, TruffleObject and ForeignAccess-related classes. Jaroslav Tulach <jaroslav.tulach@oracle.com> parents: diff changeset	413 }

Mercurial > hg > truffle

annotate truffle/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/Message.java @ 22154:cc195dd45121