Mercurial > hg > truffle

changeset 22056:2c65e6da65ea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Providing information about API packages
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Tue, 04 Aug 2015 16:54:07 +0200
parents 2867e02e6fdb
children 8cb430bc5312
files truffle/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/package-info.java truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/package-info.java truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/package.html truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/nodes/serial/package-info.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/script/package-info.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/unsafe/package-info.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/utilities/package-info.java truffle/com.oracle.truffle.tools.debug.shell/src/com/oracle/truffle/tools/debug/shell/package.html
diffstat 8 files changed, 343 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/package-info.java	Tue Aug 04 16:54:07 2015 +0200
@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ @ApiInfo(
+ group="To Review"
+ )
+ */
+
+/**
+ * {@link com.oracle.truffle.api.dsl.NodeChild Domain specific language}
+ * for creating
+ * {@link com.oracle.truffle.api.nodes nodes AST nodes}.
+ * Rather than building {@link com.oracle.truffle.api.nodes.Node nodes}
+ * from scratch, consider using
+ * the {@link com.oracle.truffle.api.dsl.NodeChild DSL}.
+ */
+package com.oracle.truffle.api.dsl;
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/package-info.java	Tue Aug 04 16:54:07 2015 +0200
@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ @ApiInfo(
+ group="To Review"
+ )
+ */
+
+/** Optimal object model.
+ */
+package com.oracle.truffle.api.object;
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/package.html	Tue Aug 04 16:54:07 2015 +0200
@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<!--
+
+Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This code is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License version 2 only, as
+published by the Free Software Foundation.  Oracle designates this
+particular file as subject to the "Classpath" exception as provided
+by Oracle in the LICENSE file that accompanied this code.
+
+This code is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+version 2 for more details (a copy is included in the LICENSE file that
+accompanied this code).
+
+You should have received a copy of the GNU General Public License version
+2 along with this work; if not, write to the Free Software Foundation,
+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+or visit www.oracle.com if you need additional information or have any
+questions.
+-->
+<html>
+    <p>
+    This package contains basic tests of the Truffle API and serves at the same time as an
+    introduction to the Truffle API for language implementors. Every test gives an example on how to
+    use the construct explained in the class description.
+    </p>
+
+    <p>
+    Truffle is a language implementation framework. A guest language method is represented as a tree
+    of executable nodes. The framework provides mechanisms for those trees to call each other.
+    Additionally it contains dedicated data structures for storing data local to a tree invocation.
+    </p>
+
+    <p>
+    This introduction to Truffle contains items in the following recommended order:
+
+    <ul>
+    <li>How to get access to the Truffle runtime?
+    {@link com.oracle.truffle.api.test.TruffleRuntimeTest}</li>
+    <li>How to create a root node? {@link com.oracle.truffle.api.test.RootNodeTest}</li>
+    <li>How to create a child node and link it with its parent?
+    {@link com.oracle.truffle.api.test.ChildNodeTest}</li>
+    <li>How to create an array of child nodes? {@link com.oracle.truffle.api.test.ChildrenNodesTest}
+    </li>
+    <li>Why are final fields in node classes important?
+    {@link com.oracle.truffle.api.test.FinalFieldTest}</li>
+    <li>How to replace one node with another node and what for?
+    {@link com.oracle.truffle.api.test.ReplaceTest}</li>
+    <li>How to let one Truffle tree invoke another one? {@link com.oracle.truffle.api.test.CallTest}
+    </li>
+    <li>How to pass arguments when executing a tree?
+    {@link com.oracle.truffle.api.test.ArgumentsTest}</li>
+    <li>How to use frames and frame slots to store values local to an activation?
+    {@link com.oracle.truffle.api.test.FrameTest}</li>
+    <li>How to use type specialization and speculation for frame slots?
+    {@link com.oracle.truffle.api.test.FrameSlotTypeSpecializationTest}</li>
+    <li>How to use type specialization and speculation for node return values?
+    {@link com.oracle.truffle.api.test.ReturnTypeSpecializationTest}</li>
+    <li>How to "instrument" an AST with nodes that can provide access to runtime state from external
+    tools {@code com.oracle.truffle.api.test.instrument.InstrumentationTest}</li>
+    </ul>
+</html>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/nodes/serial/package-info.java	Tue Aug 04 16:54:07 2015 +0200
@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ @ApiInfo(
+ group="Experimental"
+ )
+ */
+
+/** Persisting AST nodes.
+ */
+package com.oracle.truffle.api.nodes.serial;
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/script/package-info.java	Tue Aug 04 16:54:07 2015 +0200
@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ @ApiInfo(
+ group="Deprecated"
+ )
+ */
+
+/**
+ * Will change completely.
+ */
+package com.oracle.truffle.api.script;
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/unsafe/package-info.java	Tue Aug 04 16:54:07 2015 +0200
@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ @ApiInfo(
+ group="Deprecated"
+ )
+ */
+
+/** Will it be removed(?).
+ */
+package com.oracle.truffle.api.unsafe;
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/utilities/package-info.java	Tue Aug 04 16:54:07 2015 +0200
@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ @ApiInfo(
+ group="To Review"
+ )
+ */
+
+/** Various utility methods.
+ */
+package com.oracle.truffle.api.utilities;
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.tools.debug.shell/src/com/oracle/truffle/tools/debug/shell/package.html	Tue Aug 04 16:54:07 2015 +0200
@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<!--
+
+Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This code is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License version 2 only, as
+published by the Free Software Foundation.  Oracle designates this
+particular file as subject to the "Classpath" exception as provided
+by Oracle in the LICENSE file that accompanied this code.
+
+This code is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+version 2 for more details (a copy is included in the LICENSE file that
+accompanied this code).
+
+You should have received a copy of the GNU General Public License version
+2 along with this work; if not, write to the Free Software Foundation,
+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+or visit www.oracle.com if you need additional information or have any
+questions.
+-->
+<html>
+<body>
+ This package contains an experimental framework for building simple command-line oriented
+ debuggers that work with Truffle-implemented languages; it is used mainly for testing Truffle's
+ built-in , which actually provides the
+ debugging services.
+ <p>
+ Truffle debugging is made possible by the general purpose Instrumentation Framework built into
+ the Truffle platform. Some online documentation for the Instrumentation Framework is available
+ online:
+ <q> <a href="https://wiki.openjdk.java.net/display/Graal/Instrumentation+API">https://wiki.
+ openjdk.java.net/display/Graal/Instrumentation+API</a> </q>
+ <p>
+ Building one of these command line debuggers requires creating language-specific instances of:
+ <ol>
+ <li>DebugEngine, noting that this instance also
+ depends on related services provided by the language implementation,</li>
+ <li>{@link com.oracle.truffle.tools.debug.shell.REPLServer}, best accomplished by copying the
+ implementation for Truffle's demonstration language "Simple" (a.k.a. "SL").</li>
+ </ol>
+
+ <strong>Disclaimer: </strong> although these command line debuggers are useful, they are not
+ intended, and will not be maintained as, fully functioning debuggers. They should be considered
+ valuable tools for the maintainers of the
+ DebugEngine, as well as for Truffle language
+ implementors for whom concurrent access to any kind debugging services can be quite helpful.
+ <p>
+ <strong>Note:</strong> Both the functionality and API for this package are under active
+ development.
+ <p>
+    </body>
+</html>