com.oracle.truffle.api.profiles.Profile Maven / Gradle / Ivy
Show all versions of truffle-api Show documentation
/*
* 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.
*/
package com.oracle.truffle.api.profiles;
import com.oracle.truffle.api.Assumption;
import com.oracle.truffle.api.CompilerDirectives;
import com.oracle.truffle.api.CompilerDirectives.CompilationFinal;
import com.oracle.truffle.api.Truffle;
import com.oracle.truffle.api.TruffleRuntime;
import com.oracle.truffle.api.nodes.Node;
import com.oracle.truffle.api.nodes.NodeCloneable;
import com.oracle.truffle.api.nodes.RootNode;
/**
*
* A profile is a Truffle utility class that uses the {@link CompilerDirectives Truffle compiler
* directives} to guard for and/or forward runtime information to the compiler.
*
*
*
* Usage: Profiles should be stored in final
or {@link CompilationFinal
* compilation final} fields of node classes to ensure that they can get optimized properly.
* Profiles must not be shared between ASTs. Using the same profile multiple times in a single
* {@link Node node} or in multiple {@link Node nodes} which {@link Node#getRootNode() link} to the
* same {@link RootNode root} is allowed. Never store profiles inside runtime values that
* leave the scope of the originating AST. This limitation exists because the used mechanism to
* invalidate compiled code performs local invalidations only. For global speculations use
* {@link Assumption assumptions} instead.
*
*
*
* Compilation: Some profiles like {@link BranchProfile branch} profiles do not induce
* additional overhead in compiled code. Others like {@link ValueProfile value} profiles might
* require a runtime check to verify their assumptions which are forwarded to the compiler. Even if
* profiles do not induce direct overhead in compiled code it still might get invalidated as a
* result of using profiles. Invalidating profiles will result in the invalidation of compiled code.
* It is therefore essential to place these profiles in way that is neither too aggressive nor too
* conservative.
*
*
*
* Footprint: Whether profiling information can be forwarded to the compiler depends on the
* capabilities of the {@link TruffleRuntime runtime system}. If the runtime returns
* true
in {@link TruffleRuntime#isProfilingEnabled()} then runtime information will
* get collected. This comes at at the cost of additional overhead and footprint in interpreted
* mode. Thats why the factory methods of profiles can return implementations where profiling is
* disabled. Using disabled profiles makes sense for runtimes that are unable to use the collected
* profiling information. Even runtime implementations that are able to use this information might
* decide to turn off profiling for benchmarking purposes.
*
*
*
* Profile subclasses:
*
* - {@link BranchProfile} to profile on unlikely branches like errors.
* - {@link ConditionProfile} to profile on conditionals or boolean values.
* - {@link LoopConditionProfile} to profile on conditionals of loops with special support for
* counted loops.
* - {@link ValueProfile} to profile on properties like type and identity of values.
* - {@link ByteValueProfile} to profile on
byte
values.
* - {@link IntValueProfile} to profile on
int
values.
* - {@link LongValueProfile} to profile on
long
values.
* - {@link FloatValueProfile} to profile on
float
values.
* - {@link DoubleValueProfile} to profile on
double
values.
* - {@link PrimitiveValueProfile} to profile on objects by identity and on primitives by value.
*
*
*
*
* @see Assumption
* @since 0.10
*/
public abstract class Profile extends NodeCloneable {
static boolean isProfilingEnabled() {
boolean enabled;
try {
enabled = Truffle.getRuntime().isProfilingEnabled();
} catch (LinkageError ex) {
// running on old version of Graal
enabled = true;
}
return enabled;
}
Profile() {
/* We don't to allow custom profiles. We want to evolve this API further first. Sorry. */
}
String toStringDisabled(Class> profileClass) {
return String.format("%s(DISABLED)", profileClass.getSimpleName());
}
String toString(Class> profileClass, boolean uninitialized, boolean generic, String specialization) {
String s;
if (uninitialized) {
s = "UNINITIALIZED";
} else if (generic) {
s = "GENERIC";
} else {
s = specialization == null ? "" : specialization;
}
return String.format("%s(%s)@%s", profileClass.getSimpleName(), s, Integer.toHexString(this.hashCode()));
}
}