Mercurial > hg > graal-compiler

comparison graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/Fallback.java @ 18128:7b6a4ae58de4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle-DSL: improve JavaDoc for @Fallback.
author Christian Humer <christian.humer@gmail.com>
date Tue, 21 Oct 2014 00:18:29 +0200
parents 9f38d222fa6c
children
comparison
equal deleted inserted replaced
18127:7cefdad149ad 18128:7b6a4ae58de4
1 /* 1 /*
2 * Copyright (c) 2012, 2012, Oracle and/or its affiliates. All rights reserved. 2 * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 * 4 *
5 * This code is free software; you can redistribute it and/or modify it 5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as 6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this 7 * published by the Free Software Foundation. Oracle designates this
24 */ 24 */
25 package com.oracle.truffle.api.dsl; 25 package com.oracle.truffle.api.dsl;
26 26
27 import java.lang.annotation.*; 27 import java.lang.annotation.*;
28 28
29 import com.oracle.truffle.api.nodes.*;
30
29 /** 31 /**
32 * <p>
33 * A method annotated with {@link Fallback} is treated as a {@link Specialization} that implicitly
34 * links all the guards of all other declared {@link Specialization} annotated methods of the
35 * operation in a negated form. As a consequence it cannot declare any other guards. The expected
36 * signature of the method must match to the signature of a {@link Specialization} with the
37 * additional limitation that only generically executable argument types are allowed. A generically
38 * executable argument is a an argument hat can be executed from the child {@link Node} using an
39 * execute method without {@link UnsupportedOperationException}. In many cases the generically
40 * executable type is {@link Object}. An operation is limited to just one {@link Fallback}
41 * specialization which is always ordered at the end of the specialization chain.
42 * </p>
30 * 43 *
44 * <p>
45 * A simple example showing the use of the {@link Fallback} annotation in a DSL operation:
46 * </p>
47 *
48 * <pre>
49 * &#064;Specialization int doInt(int a) {..}
50 * &#064;Specialization int doDouble(double a) {..}
51 * &#064;Fallback int orElse(Object a) {..}
52 * </pre>
53 *
54 * <p>
55 * The previous example could be redeclared just using {@link Specialization} annotated methods as
56 * follows:
57 * </p>
58 *
59 * <pre>
60 * &#064;Specialization int doInt(int a) {..}
61 * &#064;Specialization int doDouble(double a) {..}
62 * &#064;Specialization(guard={"!isInt(a)", "!isDouble(a)"})
63 * int orElse(Object a) {..}
64 * </pre>
65 *
66 * <p>
67 * <b>Performance note:</b> For operations with a lot of {@link Specialization} annotated methods
68 * the use of {@link Fallback} might generate a guard that is very big. Try to avoid the use of
69 * {@link Fallback} for specializations that are significantly important for peak performance.
70 * </p>
71 *
72 * @see Specialization
73 * @see NodeChild
31 */ 74 */
32 @Retention(RetentionPolicy.CLASS) 75 @Retention(RetentionPolicy.CLASS)
33 @Target({ElementType.METHOD}) 76 @Target({ElementType.METHOD})
34 public @interface Fallback { 77 public @interface Fallback {
35 78