Mercurial > hg > truffle

comparison truffle/com.oracle.truffle.api.profiles/src/com/oracle/truffle/api/profiles/Profile.java @ 22503:828c67903db2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Moving profiles into their own project to ensure the core API doesn't reference these utility classes.
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Thu, 17 Dec 2015 10:01:38 +0100
parents truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/profiles/Profile.java@a63bda98cfdb
children d80a5ff56f51
comparison
equal deleted inserted replaced
22502:d2b4fe945c23 22503:828c67903db2
1 /*
2 * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
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
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package com.oracle.truffle.api.profiles;
26
27 import com.oracle.truffle.api.Assumption;
28 import com.oracle.truffle.api.CompilerDirectives;
29 import com.oracle.truffle.api.CompilerDirectives.CompilationFinal;
30 import com.oracle.truffle.api.TruffleRuntime;
31 import com.oracle.truffle.api.nodes.Node;
32 import com.oracle.truffle.api.nodes.NodeCloneable;
33 import com.oracle.truffle.api.nodes.RootNode;
34
35 /**
36 * <p>
37 * A profile is a Truffle utility class that uses the {@link CompilerDirectives Truffle compiler
38 * directives} to guard for and/or forward runtime information to the compiler.
39 * </p>
40 *
41 * <p>
42 * <b>Usage:</b> Profiles should be stored in <code>final</code> or {@link CompilationFinal
43 * compilation final} fields of node classes to ensure that they can get optimized properly.
44 * Profiles must not be shared between ASTs. Using the same profile multiple times in a single
45 * {@link Node node} or in multiple {@link Node nodes} which {@link Node#getRootNode() link} to the
46 * same {@link RootNode root} is allowed. <b>Never</b> store profiles inside runtime values that
47 * leave the scope of the originating AST. This limitation exists because the used mechanism to
48 * invalidate compiled code performs local invalidations only. For global speculations use
49 * {@link Assumption assumptions} instead.
50 * </p>
51 *
52 * <p>
53 * <b>Compilation:</b> Some profiles like {@link BranchProfile branch} profiles do not induce
54 * additional overhead in compiled code. Others like {@link ValueProfile value} profiles might
55 * require a runtime check to verify their assumptions which are forwarded to the compiler. Even if
56 * profiles do not induce direct overhead in compiled code it still might get invalidated as a
57 * result of using profiles. Invalidating profiles will result in the invalidation of compiled code.
58 * It is therefore essential to place these profiles in way that is neither too aggressive nor too
59 * conservative.
60 * </p>
61 *
62 * <p>
63 * <b>Footprint:</b> Whether profiling information can be forwarded to the compiler depends on the
64 * capabilities of the {@link TruffleRuntime runtime system}. If the runtime returns
65 * <code>true</code> in {@link TruffleRuntime#isProfilingEnabled()} then runtime information will
66 * get collected. This comes at at the cost of additional overhead and footprint in interpreted
67 * mode. Thats why the factory methods of profiles can return implementations where profiling is
68 * disabled. Using disabled profiles makes sense for runtimes that are unable to use the collected
69 * profiling information. Even runtime implementations that are able to use this information might
70 * decide to turn off profiling for benchmarking purposes.
71 * </p>
72 *
73 * <p>
74 * Profile subclasses:
75 * <ul>
76 * <li> {@link BranchProfile} to profile on unlikely branches like errors.</li>
77 * <li> {@link ConditionProfile} to profile on conditionals or boolean values.</li>
78 * <li> {@link LoopConditionProfile} to profile on conditionals of loops with special support for
79 * counted loops.</li>
80 * <li> {@link ValueProfile} to profile on properties like type and identity of values.</li>
81 * <li> {@link ByteValueProfile} to profile on <code>byte</code> values.</li>
82 * <li> {@link IntValueProfile} to profile on <code>int</code> values.</li>
83 * <li> {@link LongValueProfile} to profile on <code>long</code> values.</li>
84 * <li> {@link FloatValueProfile} to profile on <code>float</code> values.</li>
85 * <li> {@link DoubleValueProfile} to profile on <code>double</code> values.</li>
86 * <li> {@link PrimitiveValueProfile} to profile on objects by identity and on primitives by value.</li>
87 * </ul>
88 * </p>
89 *
90 * @see Assumption
91 */
92 public abstract class Profile extends NodeCloneable {
93
94 Profile() {
95 /* We don't to allow custom profiles. We want to evolve this API further first. Sorry. */
96 }
97
98 String toStringDisabled(Class<?> profileClass) {
99 return String.format("%s(DISABLED)", profileClass.getSimpleName());
100 }
101
102 String toString(Class<?> profileClass, boolean uninitialized, boolean generic, String specialization) {
103 String s;
104 if (uninitialized) {
105 s = "UNINITIALIZED";
106 } else if (generic) {
107 s = "GENERIC";
108 } else {
109 s = specialization == null ? "" : specialization;
110 }
111 return String.format("%s(%s)@%s", profileClass.getSimpleName(), s, Integer.toHexString(this.hashCode()));
112 }
113
114 }