diff --git a/LICENSE.md b/LICENSE.md index 68eee354f..041a360dd 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,4 +1,4 @@ -Copyright (c) 2012, 2016 Oracle and/or its affiliates. All rights reserved. +Copyright (c) 2012, 2018 Oracle and/or its affiliates. All rights reserved. The Universal Permissive License (UPL), Version 1.0 diff --git a/README.md b/README.md index fa437026d..0c7c592c9 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ A simple demonstration language built using Truffle for the GraalVM. SimpleLanguage is heavily documented to explain the how and why of writing a Truffle language. A good way to read this documentation is to generate HTML of -the JavaDoc comments and read that, and then read the source alongside the -comments. +the JavaDoc comments with `mvn compile javadoc:aggregate` and read that, +and then read the source alongside the comments. This repository is licensed under the permissive UPL licence. Fork it to begin your own Truffle language. diff --git a/component/pom.xml b/component/pom.xml index 9df3f77ad..ab0f9e106 100644 --- a/component/pom.xml +++ b/component/pom.xml @@ -14,6 +14,7 @@ exec-maven-plugin org.codehaus.mojo + 1.6.0 make_component diff --git a/language/pom.xml b/language/pom.xml index 64fabc0f7..41811adf7 100644 --- a/language/pom.xml +++ b/language/pom.xml @@ -12,6 +12,7 @@ org.apache.maven.plugins maven-eclipse-plugin + 2.10 true true diff --git a/language/src/main/java/com/oracle/truffle/sl/SLException.java b/language/src/main/java/com/oracle/truffle/sl/SLException.java index 4418997de..0ddb93bc5 100644 --- a/language/src/main/java/com/oracle/truffle/sl/SLException.java +++ b/language/src/main/java/com/oracle/truffle/sl/SLException.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -80,6 +80,9 @@ public Node getLocation() { /** * Provides a user-readable message for run-time type errors. SL is strongly typed, i.e., there * are no automatic type conversions of values. + * @param operation the node representing the failed operation. + * @param values the values that caused the type error. + * @return an exception containing a description of the run-time error. */ @TruffleBoundary public static SLException typeError(Node operation, Object... values) { diff --git a/language/src/main/java/com/oracle/truffle/sl/SLLanguage.java b/language/src/main/java/com/oracle/truffle/sl/SLLanguage.java index b4c7e3d2f..a2a79347d 100644 --- a/language/src/main/java/com/oracle/truffle/sl/SLLanguage.java +++ b/language/src/main/java/com/oracle/truffle/sl/SLLanguage.java @@ -154,7 +154,7 @@ * {@link SLWhileNode while} with {@link SLBreakNode break} and {@link SLContinueNode continue}, * {@link SLReturnNode return}. *
  • Debugging control: {@link SLDebuggerNode debugger} statement uses - * {@link DebuggerTags#AlwaysHalt} tag to halt the execution when run under the debugger. + * {@link DebuggerTags.AlwaysHalt} tag to halt the execution when run under the debugger. *
  • Function calls: {@link SLInvokeNode invocations} are efficiently implemented with * {@link SLDispatchNode polymorphic inline caches}. *
  • Object access: {@link SLReadPropertyNode} uses {@link SLReadPropertyCacheNode} as the diff --git a/language/src/main/java/com/oracle/truffle/sl/builtins/SLGetSizeBuiltin.java b/language/src/main/java/com/oracle/truffle/sl/builtins/SLGetSizeBuiltin.java index 4a6764cd0..e2b4f04bf 100644 --- a/language/src/main/java/com/oracle/truffle/sl/builtins/SLGetSizeBuiltin.java +++ b/language/src/main/java/com/oracle/truffle/sl/builtins/SLGetSizeBuiltin.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -51,7 +51,7 @@ /** * Built-in function that queries the size property of a foreign object. See - * Messages.GET_SIZE. + * {@link Message#GET_SIZE} */ @NodeInfo(shortName = "getSize") public abstract class SLGetSizeBuiltin extends SLBuiltinNode { diff --git a/language/src/main/java/com/oracle/truffle/sl/builtins/SLHasSizeBuiltin.java b/language/src/main/java/com/oracle/truffle/sl/builtins/SLHasSizeBuiltin.java index 29cc26991..2c9d60f0c 100644 --- a/language/src/main/java/com/oracle/truffle/sl/builtins/SLHasSizeBuiltin.java +++ b/language/src/main/java/com/oracle/truffle/sl/builtins/SLHasSizeBuiltin.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -49,7 +49,7 @@ /** * Built-in function that queries if the foreign object has a size. See - * Messages.HAS_SIZE. + * {@link Message#HAS_SIZE}. */ @NodeInfo(shortName = "hasSize") public abstract class SLHasSizeBuiltin extends SLBuiltinNode { diff --git a/language/src/main/java/com/oracle/truffle/sl/builtins/SLIsExecutableBuiltin.java b/language/src/main/java/com/oracle/truffle/sl/builtins/SLIsExecutableBuiltin.java index 64de936b2..ffadf8d46 100644 --- a/language/src/main/java/com/oracle/truffle/sl/builtins/SLIsExecutableBuiltin.java +++ b/language/src/main/java/com/oracle/truffle/sl/builtins/SLIsExecutableBuiltin.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -49,7 +49,7 @@ /** * Built-in function that queries if the foreign object is executable. See - * Messages.IS_EXECUTABLE. + * {@link }Messages#IS_EXECUTABLE}. */ @NodeInfo(shortName = "isExecutable") public abstract class SLIsExecutableBuiltin extends SLBuiltinNode { diff --git a/language/src/main/java/com/oracle/truffle/sl/builtins/SLIsNullBuiltin.java b/language/src/main/java/com/oracle/truffle/sl/builtins/SLIsNullBuiltin.java index 4cae0a4c7..4d0307904 100644 --- a/language/src/main/java/com/oracle/truffle/sl/builtins/SLIsNullBuiltin.java +++ b/language/src/main/java/com/oracle/truffle/sl/builtins/SLIsNullBuiltin.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -49,7 +49,7 @@ /** * Built-in function that queries if the foreign object is a null value. See - * Messages.IS_NULL. + * {@link Message#IS_NULL}. */ @NodeInfo(shortName = "isNull") public abstract class SLIsNullBuiltin extends SLBuiltinNode { diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/SLExpressionNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/SLExpressionNode.java index 2d5c3dcb4..d8144d4f5 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/SLExpressionNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/SLExpressionNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -64,12 +64,15 @@ public abstract class SLExpressionNode extends SLStatementNode { /** * The execute method when no specialization is possible. This is the most general case, * therefore it must be provided by all subclasses. + * @param frame the frame containing local variables. + * @return the result of executing the expression node. */ public abstract Object executeGeneric(VirtualFrame frame); /** * When we use an expression at places where a {@link SLStatementNode statement} is already * sufficient, the return value is just discarded. + * @param frame the frame containing local variables. */ @Override public void executeVoid(VirtualFrame frame) { diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/SLStatementNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/SLStatementNode.java index 89448b2d2..b134faac4 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/SLStatementNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/SLStatementNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -161,6 +161,7 @@ public WrapperNode createWrapper(ProbeNode probe) { /** * Execute this node as as statement, where no return value is necessary. + * @param frame the local variable frame. */ public abstract void executeVoid(VirtualFrame frame); diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/SLTypes.java b/language/src/main/java/com/oracle/truffle/sl/nodes/SLTypes.java index 7930dfa95..7518fe40d 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/SLTypes.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/SLTypes.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -66,6 +66,8 @@ public abstract class SLTypes { * check that the Truffle DSL would generate. For {@link SLNull}, we do not need an * {@code instanceof} check, because we know that there is only a {@link SLNull#SINGLETON * singleton} instance. + * @param value the object to check for nullity. + * @return true if the object is equal to the null singleton. */ @TypeCheck(SLNull.class) public static boolean isSLNull(Object value) { @@ -76,6 +78,8 @@ public static boolean isSLNull(Object value) { * Example of a manually specified type cast that replaces the automatically generated type cast * that the Truffle DSL would generate. For {@link SLNull}, we do not need an actual cast, * because we know that there is only a {@link SLNull#SINGLETON singleton} instance. + * @param value the object to cast to the null singleton. + * @return the null singleton. */ @TypeCast(SLNull.class) public static SLNull asSLNull(Object value) { @@ -89,6 +93,8 @@ public static SLNull asSLNull(Object value) { * only has an arbitrary precision Number type (implemented as {@link SLBigNumber}, and * {@code long} is only used as a performance optimization to avoid the costly * {@link SLBigNumber} arithmetic for values that fit into a 64-bit primitive value. + * @param value the long value to convert to a {@link SLBigNumber}. + * @return the {@link SLBigNumber} corresponding to the long value. */ @ImplicitCast @TruffleBoundary diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLPropertyCacheNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLPropertyCacheNode.java index 02b684456..63de30f86 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLPropertyCacheNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLPropertyCacheNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016, 2016, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -67,17 +67,19 @@ protected static Shape lookupShape(DynamicObject receiver) { } /** - * Property names can be arbitrary SL objects. We could call {@link Object.equals}, but that is - * generally a bad idea and therefore discouraged in Truffle.{@link Object.equals} is a virtual + * Property names can be arbitrary SL objects. We could call {@link Object#equals}, but that is + * generally a bad idea and therefore discouraged in Truffle.{@link Object#equals} is a virtual * call that can call possibly large methods that we do not want in compiled code. For example, * we do not want {@link SLBigNumber#equals} in compiled code but behind a - * {@link TruffleBoundary). Therfore, we check types individually. The checks are semantically - * the same as {@link SLEqualNode}. + * {@link com.oracle.truffle.api.CompilerDirectives.TruffleBoundary}. Therefore, we check types individually. + * The checks are semantically the same as {@link SLEqualNode}. *

    * Note that the {@code cachedName} is always a constant during compilation. Therefore, compiled * code is always reduced to a single {@code if} that only checks whether the {@code name} has * the same type. - * + * @param cachedName the cached property name that we want to compare to name. + * @param name the value to compare against. + * @return true if {@code cachedName} and {@code name} are equal. */ protected static boolean namesEqual(Object cachedName, Object name) { if (cachedName instanceof Long && name instanceof Long) { diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLReadPropertyCacheNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLReadPropertyCacheNode.java index ad2d6d048..01fd544f8 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLReadPropertyCacheNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLReadPropertyCacheNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2013, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -57,6 +57,12 @@ public abstract class SLReadPropertyCacheNode extends SLPropertyCacheNode { /** * Polymorphic inline cache for a limited number of distinct property names and shapes. + * @param receiver the object to receive the read value. + * @param name the name of the required property. + * @param cachedName the cache object to store the name in. + * @param shape the shape of {@code receiver}. + * @param location the location of the property. + * @return the read object. */ @Specialization(limit = "CACHE_LIMIT", // guards = { @@ -90,6 +96,10 @@ protected Location lookupLocation(Shape shape, Object name) { /** * The generic case is used if the number of shapes accessed overflows the limit of the * polymorphic inline cache. + * @param receiver the object to receive the read value. + * @param name the name of the required property. + * @return the requested property. + * @throws SLUndefinedNameException if the property does not exist. */ @TruffleBoundary @Specialization(replaces = {"readCached"}, guards = "receiver.getShape().isValid()") diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLReadPropertyNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLReadPropertyNode.java index c83910af2..66b4a6af2 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLReadPropertyNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLReadPropertyNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2013, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -86,6 +86,11 @@ protected Object read(DynamicObject receiver, Object name, /** * Language interoperability: if the receiver object is a foreign value we use Truffle's interop * API to access the foreign data. + * @param receiver the foreign object to receive the read value. + * @param name the name of the foreign property to retrieve. + * @param foreignReadNode the AST node that will handle the read request. + * @param toSLTypeNode the node to convert the foreign value to the corresponding SL type. + * @return the foreign value. */ @Specialization(guards = "!isSLObject(receiver)") protected Object readForeign(TruffleObject receiver, Object name, @@ -109,6 +114,10 @@ protected Object readForeign(TruffleObject receiver, Object name, /** * When no specialization fits, the receiver is either not an object (which is a type error), or * the object has a shape that has been invalidated. + * @param r the receiver object (unused). + * @param name the name of the property to read. + * @return nothing - always throws an exception. + * @throws SLUndefinedNameException denoting the value can't be read. */ @Fallback protected Object typeError(@SuppressWarnings("unused") Object r, Object name) { diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLWritePropertyCacheNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLWritePropertyCacheNode.java index 0d0eb6bcb..f0a007c92 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLWritePropertyCacheNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLWritePropertyCacheNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2013, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -57,8 +57,13 @@ public abstract class SLWritePropertyCacheNode extends SLPropertyCacheNode { public abstract void executeWrite(DynamicObject receiver, Object name, Object value); /** - * Polymorphic inline cache for writing a property that already exists (no shape change is - * necessary). + * Polymorphic inline cache for writing a property that already exists (no shape change is necessary). + * @param receiver the object to receive the written value. + * @param name the name of the property to write. + * @param value the value to write to the property. + * @param cachedName the cache for the property. + * @param shape the property-to-location mapping. + * @param location the location for the property. */ @Specialization(limit = "CACHE_LIMIT", // guards = { @@ -70,7 +75,9 @@ public abstract class SLWritePropertyCacheNode extends SLPropertyCacheNode { assumptions = { "shape.getValidAssumption()" }) - protected static void writeExistingPropertyCached(DynamicObject receiver, @SuppressWarnings("unused") Object name, Object value, + protected static void writeExistingPropertyCached(DynamicObject receiver, + @SuppressWarnings("unused") Object name, + Object value, @SuppressWarnings("unused") @Cached("name") Object cachedName, @Cached("lookupShape(receiver)") Shape shape, @Cached("lookupLocation(shape, name, value)") Location location) { @@ -84,8 +91,15 @@ protected static void writeExistingPropertyCached(DynamicObject receiver, @Suppr } /** - * Polymorphic inline cache for writing a property that does not exist yet (shape change is - * necessary). + * Polymorphic inline cache for writing a property that does not exist yet (shape change is necessary). + * @param receiver the object to receive the written value. + * @param name the name of the property to write. + * @param value the value to write to the property. + * @param cachedName the cache for the property. + * @param oldShape the old property-to-location mapping. + * @param oldLocation the old location for the property. + * @param newShape the new property-to-location mapping. + * @param newLocation the new location for the property. */ @Specialization(limit = "CACHE_LIMIT", // guards = { @@ -114,7 +128,12 @@ protected static void writeNewPropertyCached(DynamicObject receiver, Object name } } - /** Try to find the given property in the shape. */ + /** + * Try to find the given property in the shape. + * @param shape the shape to look the property up in. + * @param name the name of the property. + * @return the location of the property, or {@code null} if it does not exist. + */ protected static Location lookupLocation(Shape shape, Object name) { CompilerAsserts.neverPartOfCompilation(); @@ -128,8 +147,12 @@ protected static Location lookupLocation(Shape shape, Object name) { } /** - * Try to find the given property in the shape. Also returns null when the value cannot be store - * into the location. + * Try to find the given property in the shape. Also returns null when the value cannot be stored + * into the location. No actual assignment is done. + * @param shape the shape to look the property up in. + * @param name the name of the property. + * @param value the value that the property is going to be stored into the location. + * @return the location of the property, or null if it does not exist or the value can't be stored into it. */ protected static Location lookupLocation(Shape shape, Object name, Object value) { Location location = lookupLocation(shape, name); @@ -152,12 +175,20 @@ protected static Shape defineProperty(Shape oldShape, Object name, Object value) * guard of {@link SLWritePropertyCacheNode#writeNewPropertyCached} because there we perform a * shape transition, i.e., we are not actually setting the value of the new location - we only * transition to this location as part of the shape change. + * @param location the location to test the value against. + * @param value the value to check the location can be set to. + * @return true if the location can be set to the value. */ protected static boolean canSet(Location location, Object value) { return location.canSet(value); } - /** See {@link #canSet} for the difference between the two methods. */ + /** + * See {@link #canSet} for the difference between the two methods. + * @param location the location to test the value against. + * @param value the value to check can be stored in the location . + * @return true if the value can be stored in the location. + */ protected static boolean canStore(Location location, Object value) { return location.canStore(value); } @@ -165,6 +196,9 @@ protected static boolean canStore(Location location, Object value) { /** * The generic case is used if the number of shapes accessed overflows the limit of the * polymorphic inline cache. + * @param receiver the object to receive the property, + * @param name the name of the property. + * @param value the value of the property. */ @TruffleBoundary @Specialization(replaces = {"writeExistingPropertyCached", "writeNewPropertyCached"}, guards = {"receiver.getShape().isValid()"}) diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLWritePropertyNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLWritePropertyNode.java index 2f210e4cd..7cca95b68 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLWritePropertyNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/access/SLWritePropertyNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2013, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -89,6 +89,10 @@ protected Object write(DynamicObject receiver, Object name, Object value, /** * Language interoperability: If the receiver object is a foreign value we use Truffle's interop * API to access the foreign data. + * @param receiver the object to receive the property. + * @param name the property name. + * @param value the property value. + * @param foreignWriteNode the foreign value node that the value will be written to. */ @Specialization(guards = "!isSLObject(receiver)") protected void writeForeign(TruffleObject receiver, Object name, Object value, @@ -107,6 +111,10 @@ protected void writeForeign(TruffleObject receiver, Object name, Object value, /** * When no specialization fits, the receiver is not an object (which is a type error). + * @param r the receiver (unused). + * @param name the name of the property. + * @param value the value of the property (unused). + * @throws SLUndefinedNameException always. */ @Fallback @SuppressWarnings("unused") diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/call/SLDispatchNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/call/SLDispatchNode.java index e2d576311..e40b905e4 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/call/SLDispatchNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/call/SLDispatchNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -103,10 +103,13 @@ public abstract class SLDispatchNode extends Node { * @see Cached * @see Specialization * - * @param function the dynamically provided function - * @param cachedFunction the cached function of the specialization instance + * @param function the dynamically provided function. + * @param arguments the function arguments. + * @param callTargetStable true if the the function has not been redefined. + * @param cachedTarget cached function call target root node. * @param callNode the {@link DirectCallNode} specifically created for the {@link CallTarget} in * cachedFunction. + * @return the result of the cached call. */ @Specialization(limit = "INLINE_CACHE_SIZE", // guards = "function.getCallTarget() == cachedTarget", // @@ -125,6 +128,10 @@ protected static Object doDirect(SLFunction function, Object[] arguments, * Slow-path code for a call, used when the polymorphic inline cache exceeded its maximum size * specified in INLINE_CACHE_SIZE. Such calls are not optimized any further, e.g., * no method inlining is performed. + * @param function the dynamically provided function. + * @param arguments the function arguments. + * @param callNode the function node to call. + * @return the result of the call. */ @Specialization(replaces = "doDirect") protected static Object doIndirect(SLFunction function, Object[] arguments, @@ -138,6 +145,9 @@ protected static Object doIndirect(SLFunction function, Object[] arguments, /** * When no specialization fits, the receiver is not an object (which is a type error). + * @param function the dynamically provided function. + * @param arguments the function arguments. + * @return always throws a {@link SLUndefinedNameException} */ @Fallback protected Object unknownFunction(Object function, @SuppressWarnings("unused") Object[] arguments) { @@ -147,6 +157,12 @@ protected Object unknownFunction(Object function, @SuppressWarnings("unused") Ob /** * Language interoperability: If the function is a foreign value, i.e., not a SLFunction, we use * Truffle's interop API to execute the foreign function. + * @param function the dynamically provided foreign function. + * @param arguments the function arguments. + * @param crossLanguageCallNode the child node to call the foreign function. + * @param toSLTypeNode the child node to convert the result of the foreign call to a SL value. + * @return the result of the call. + * @throws SLUndefinedNameException if the foreign function call fails. */ @Specialization(guards = "isForeignFunction(function)") protected Object doForeign(TruffleObject function, Object[] arguments, diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/controlflow/SLIfNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/controlflow/SLIfNode.java index 69310561c..0dbd5a39f 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/controlflow/SLIfNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/controlflow/SLIfNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -65,11 +65,16 @@ public final class SLIfNode extends SLStatementNode { /** Statement (or {@link SLBlockNode block}) executed when the condition is false. */ @Child private SLStatementNode elsePartNode; + /* + * Bug workaround below: JavaDoc fails to resolve {@link ConditionProfile.Counting} and + * {@link ConditionProfile.Binary} so for now just use textual references. + */ + /** * Profiling information, collected by the interpreter, capturing the profiling information of * the condition. This allows the compiler to generate better code for conditions that are - * always true or always false. Additionally the {@link CountingConditionProfile} implementation - * (as opposed to {@link BinaryConditionProfile} implementation) transmits the probability of + * always true or always false. Additionally the {@code ConditionProfile.Counting} implementation + * (as opposed to {@code ConditionProfile.Binary} implementation) transmits the probability of * the condition to be true to the compiler. */ private final ConditionProfile condition = ConditionProfile.createCountingProfile(); diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLAddNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLAddNode.java index 3bb9ad03a..3c1fecca8 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLAddNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLAddNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -77,6 +77,11 @@ public abstract class SLAddNode extends SLBinaryNode { *

    * This specialization is automatically selected by the Truffle DSL if both the left and right * operand are {@code long} values. + * @param left the left operand of the addition. + * @param right the right operand of the addition. + * @return the result of the addition. + * @throws ArithmeticException if the addition overflows. + * */ @Specialization(rewriteOn = ArithmeticException.class) protected long add(long left, long right) { @@ -94,6 +99,9 @@ protected long add(long left, long right) { * right operand is a {@code long} value. Because the {@link #add(long, long) long} * specialization} has the {@code rewriteOn} attribute, this specialization is also taken if * both input values are {@code long} values but the primitive addition overflows. + * @param left the left operand of the addition. + * @param right the right operand of the addition. + * @return the result of the addition. */ @Specialization @TruffleBoundary @@ -108,6 +116,9 @@ protected SLBigNumber add(SLBigNumber left, SLBigNumber right) { *

    * To implement these semantics, we tell the Truffle DSL to use a custom guard. The guard * function is defined in {@link #isString this class}, but could also be in any superclass. + * @param left the left operand of the string concatenation. + * @param right the right operand of the string concatenation. + * @return the result of the string concatenation. */ @Specialization(guards = "isString(left, right)") @TruffleBoundary @@ -118,6 +129,9 @@ protected String add(Object left, Object right) { /** * Guard for String concatenation: returns true if either the left or the right operand is a * {@link String}. + * @param a a potential {@link String} object. + * @param b a potential {@link String} object. + * @return true if either a or b is a {@link String} */ protected boolean isString(Object a, Object b) { return a instanceof String || b instanceof String; diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLEqualNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLEqualNode.java index fd829b228..30c9bec5e 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLEqualNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLEqualNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -101,7 +101,10 @@ protected boolean equal(SLNull left, SLNull right) { } /** - * Specialization for foreign {@link TruffleObject}s. + * Specialization for foreign {@link TruffleObject}s. This tests for object rather than value equality. + * @param left the left operand of the comparison. + * @param right the right operand of the comparison. + * @return true if the two objects are the same. */ @Specialization protected boolean equal(TruffleObject left, TruffleObject right) { @@ -120,6 +123,9 @@ protected boolean equal(TruffleObject left, TruffleObject right) { * long) and the right value "42" (type long). Since this specialization is already present, and * (without the guard) also matches (long values can be boxed to Object), it is executed. The * wrong return value is "false". + * @param left the left operand of the comparison. + * @param right the right operand of the comparison. + * @return false as we know the result is always false. */ @Specialization(guards = "differentClasses(left, right)") protected boolean equal(Object left, Object right) { diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLShortCircuitNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLShortCircuitNode.java index a75244aae..01c733f1c 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLShortCircuitNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/expression/SLShortCircuitNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -96,12 +96,16 @@ public final boolean executeBoolean(VirtualFrame frame) { /** * This method is called after the left child was evaluated, but before the right child is * evaluated. The right child is only evaluated when the return value is {code true}. + * @param leftValue the result of evaluating the left value of the expression. + * @return true if the right node needs to be evaluated. */ protected abstract boolean isEvaluateRight(boolean leftValue); /** - * Calculates the result of the short circuit operation. If the right node is not evaluated then - * false is provided. + * Calculates the result of the short circuit operation. + * @param leftValue the result of evaluating the left node. + * @param rightValue the result of evaluating the right node. + * @return the result of the short circuit evaluation. */ protected abstract boolean execute(boolean leftValue, boolean rightValue); diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/local/SLReadLocalVariableNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/local/SLReadLocalVariableNode.java index d1f7dab3d..8a595f707 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/local/SLReadLocalVariableNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/local/SLReadLocalVariableNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -65,6 +65,7 @@ public abstract class SLReadLocalVariableNode extends SLExpressionNode { /** * Returns the descriptor of the accessed local variable. The implementation of this method is * created by the Truffle DSL based on the {@link NodeField} annotation on the class. + * @return the slot describing the local variable. */ protected abstract FrameSlot getSlot(); @@ -109,6 +110,7 @@ protected Object readObject(VirtualFrame frame) { * Truffle DSL would not check the guard on every execution of the specialization. * Guards without parameters are assumed to be pure, but our guard depends on the * slot kind which can change. + * @return true if the local variable has type {@code Long}. */ protected boolean isLong(VirtualFrame frame) { return frame.getFrameDescriptor().getFrameSlotKind(getSlot()) == FrameSlotKind.Long; diff --git a/language/src/main/java/com/oracle/truffle/sl/nodes/local/SLWriteLocalVariableNode.java b/language/src/main/java/com/oracle/truffle/sl/nodes/local/SLWriteLocalVariableNode.java index 626f2544c..aedaaa1bb 100644 --- a/language/src/main/java/com/oracle/truffle/sl/nodes/local/SLWriteLocalVariableNode.java +++ b/language/src/main/java/com/oracle/truffle/sl/nodes/local/SLWriteLocalVariableNode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -60,6 +60,7 @@ public abstract class SLWriteLocalVariableNode extends SLExpressionNode { /** * Returns the descriptor of the accessed local variable. The implementation of this method is * created by the Truffle DSL based on the {@link NodeField} annotation on the class. + * @return the descriptor of the accessed local variable. */ protected abstract FrameSlot getSlot(); @@ -67,6 +68,9 @@ public abstract class SLWriteLocalVariableNode extends SLExpressionNode { * Specialized method to write a primitive {@code long} value. This is only possible if the * local variable also has currently the type {@code long} or was never written before, * therefore a Truffle DSL {@link #isLongOrIllegal(VirtualFrame) custom guard} is specified. + * @param frame the local variable frame. + * @param value the long value to write. + * @return the written {@code long} value. */ @Specialization(guards = "isLongOrIllegal(frame)") protected long writeLong(VirtualFrame frame, long value) { @@ -95,6 +99,9 @@ protected boolean writeBoolean(VirtualFrame frame, boolean value) { * guards, so there is no point in calling them. Since this method takes a value of type * {@link Object}, it is guaranteed to never fail, i.e., once we are in this specialization the * node will never be re-specialized. + * @param frame the local variable frame. + * @param value the value to write. + * @return the written value. */ @Specialization(replaces = {"writeLong", "writeBoolean"}) protected Object write(VirtualFrame frame, Object value) { @@ -118,6 +125,7 @@ protected Object write(VirtualFrame frame, Object value) { * Truffle DSL would not check the guard on every execution of the specialization. * Guards without parameters are assumed to be pure, but our guard depends on the * slot kind which can change. + * @return true if the local variable is either {@code long} or {@link FrameSlotKind#Illegal}. */ protected boolean isLongOrIllegal(VirtualFrame frame) { final FrameSlotKind kind = frame.getFrameDescriptor().getFrameSlotKind(getSlot()); diff --git a/language/src/main/java/com/oracle/truffle/sl/parser/SLNodeFactory.java b/language/src/main/java/com/oracle/truffle/sl/parser/SLNodeFactory.java index ecab7f6f3..e2a7188d8 100644 --- a/language/src/main/java/com/oracle/truffle/sl/parser/SLNodeFactory.java +++ b/language/src/main/java/com/oracle/truffle/sl/parser/SLNodeFactory.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -333,7 +333,7 @@ public SLStatementNode createReturn(Token t, SLExpressionNode valueNode) { } /** - * Returns the corresponding subclass of {@link SLExpressionNode} for binary expressions.
    + * Returns the corresponding subclass of {@link SLExpressionNode} for binary expressions. * These nodes are currently not instrumented. * * @param opToken The operator of the binary expression @@ -580,13 +580,17 @@ public SLExpressionNode createWriteProperty(SLExpressionNode receiverNode, SLExp /** * Creates source description of a single token. + * @param node the node to annotate with the source. + * @param token the parser token containing the source. */ private static void srcFromToken(SLStatementNode node, Token token) { node.setSourceSection(token.getStartIndex(), token.getText().length()); } /** - * Checks whether a list contains a null. + * Checks whether a list contains a {@code null}. + * @param list the list to scan for {@code null}s. + * @return true if the list contains a {@code null}. */ private static boolean containsNull(List list) { for (Object e : list) { diff --git a/language/src/main/java/com/oracle/truffle/sl/runtime/SLContext.java b/language/src/main/java/com/oracle/truffle/sl/runtime/SLContext.java index ce9bb734b..b8d3728c0 100644 --- a/language/src/main/java/com/oracle/truffle/sl/runtime/SLContext.java +++ b/language/src/main/java/com/oracle/truffle/sl/runtime/SLContext.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -123,14 +123,16 @@ public SLContext(SLLanguage language, TruffleLanguage.Env env, List getFunctions() { List result = new ArrayList<>(functionsObject.functions.values()); diff --git a/launcher/pom.xml b/launcher/pom.xml index df8f5314c..632d363d7 100644 --- a/launcher/pom.xml +++ b/launcher/pom.xml @@ -12,6 +12,7 @@ org.apache.maven.plugins maven-eclipse-plugin + 2.10 true true diff --git a/launcher/src/main/java/com/oracle/truffle/sl/launcher/SLMain.java b/launcher/src/main/java/com/oracle/truffle/sl/launcher/SLMain.java index 95485fa2f..51196ccaf 100644 --- a/launcher/src/main/java/com/oracle/truffle/sl/launcher/SLMain.java +++ b/launcher/src/main/java/com/oracle/truffle/sl/launcher/SLMain.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * The Universal Permissive License (UPL), Version 1.0 @@ -59,6 +59,8 @@ public final class SLMain { /** * The main entry point. + * @param args command-line arguments. + * @throws IOException if reading the SL source file fails. */ public static void main(String[] args) throws IOException { Source source; diff --git a/native/pom.xml b/native/pom.xml index b11c3525f..33baa9d13 100644 --- a/native/pom.xml +++ b/native/pom.xml @@ -14,6 +14,7 @@ exec-maven-plugin org.codehaus.mojo + 1.6.0 make_native diff --git a/pom.xml b/pom.xml index edbc1fe37..a2ece91c9 100644 --- a/pom.xml +++ b/pom.xml @@ -16,4 +16,21 @@ component native + + + + maven-javadoc-plugin + + 2.10.4 + + private + true + -Xdoclint:all + Truffle SimpleLanguage Demonstration - ${project.version} + Truffle SimpleLanguage Demonstration - ${project.version} + Copyright 2012, {currentYear} Oracle and/or its affiliates. All rights reserved. + + + +