Mercurial > hg > truffle
changeset 22056:2c65e6da65ea
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>