Mercurial > hg > truffle
changeset 18128:7b6a4ae58de4
Truffle-DSL: improve JavaDoc for @Fallback.
author | Christian Humer <christian.humer@gmail.com> |
---|---|
date | Tue, 21 Oct 2014 00:18:29 +0200 |
parents | 7cefdad149ad |
children | b3adab5f01a2 |
files | graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/Fallback.java |
diffstat | 1 files changed, 44 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/Fallback.java Mon Oct 20 23:11:40 2014 +0200 +++ b/graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/Fallback.java Tue Oct 21 00:18:29 2014 +0200 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2014, 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 @@ -26,8 +26,51 @@ import java.lang.annotation.*; +import com.oracle.truffle.api.nodes.*; + /** + * <p> + * A method annotated with {@link Fallback} is treated as a {@link Specialization} that implicitly + * links all the guards of all other declared {@link Specialization} annotated methods of the + * operation in a negated form. As a consequence it cannot declare any other guards. The expected + * signature of the method must match to the signature of a {@link Specialization} with the + * additional limitation that only generically executable argument types are allowed. A generically + * executable argument is a an argument hat can be executed from the child {@link Node} using an + * execute method without {@link UnsupportedOperationException}. In many cases the generically + * executable type is {@link Object}. An operation is limited to just one {@link Fallback} + * specialization which is always ordered at the end of the specialization chain. + * </p> * + * <p> + * A simple example showing the use of the {@link Fallback} annotation in a DSL operation: + * </p> + * + * <pre> + * @Specialization int doInt(int a) {..} + * @Specialization int doDouble(double a) {..} + * @Fallback int orElse(Object a) {..} + * </pre> + * + * <p> + * The previous example could be redeclared just using {@link Specialization} annotated methods as + * follows: + * </p> + * + * <pre> + * @Specialization int doInt(int a) {..} + * @Specialization int doDouble(double a) {..} + * @Specialization(guard={"!isInt(a)", "!isDouble(a)"}) + * int orElse(Object a) {..} + * </pre> + * + * <p> + * <b>Performance note:</b> For operations with a lot of {@link Specialization} annotated methods + * the use of {@link Fallback} might generate a guard that is very big. Try to avoid the use of + * {@link Fallback} for specializations that are significantly important for peak performance. + * </p> + * + * @see Specialization + * @see NodeChild */ @Retention(RetentionPolicy.CLASS) @Target({ElementType.METHOD})