public abstract class ValueProfile extends Profile
Specialized value profile to capture certain properties of Object
runtime values.
Value profiles require a runtime check in their initialized state to verify their profiled
assumption. Value profiles are limited to capture monomorphic profiles only. This means that if
two or more identities or classes are profiles within a single profile then the profile has no
effect and no overhead after compilation. There are specialized versions of this profile with
less interpreter footprint for boolean
, byte
,
int
, long
, float
and
double
values.
Usage example:
class SampleNode extends Node { final ValueProfile profile = ValueProfile.create{Identity,Class}Profile(); Object execute(Object input) { Object profiledValue = profile.profile(input); // compiler may know now more about profiledValue return profieldValue; } }
A profile is a Truffle utility class that uses the Truffle compiler
directives
to guard for and/or forward runtime information to the compiler. Whenever Truffle DSL
can be used inlined profiles
subclasses should be used instead of regular
profile
subclasses.
Usage: Profiles should be stored in final
or 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
node
or in multiple nodes
which link
to the
same 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
assumptions
instead.
Compilation: Some profiles like branch
profiles do not induce
additional overhead in compiled code. Others like 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 runtime system
. If the runtime returns
true
in 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:
BranchProfile
to profile on unlikely branches like errors.ConditionProfile
to profile on conditionals or boolean values.LoopConditionProfile
to profile on conditionals of loops with special support for
counted loops.ValueProfile
to profile on properties like type and identity of values.ByteValueProfile
to profile on byte
values.IntValueProfile
to profile on int
values.LongValueProfile
to profile on long
values.FloatValueProfile
to profile on float
values.DoubleValueProfile
to profile on double
values.PrimitiveValueProfile
to profile on objects by identity and on primitives by value.
ValueProfile.createIdentityProfile()
,
ValueProfile.createClassProfile()
Modifier and Type | Method and Description |
---|---|
static ValueProfile |
create()
Returns a value profile that profiles the exact class of a value.
|
static ValueProfile |
createClassProfile()
Returns a value profile that profiles the exact class of a value.
|
static ValueProfile |
createIdentityProfile()
Returns a value profile that profiles the object identity of a value.
|
static ValueProfile |
getUncached()
Returns the uncached version of the profile.
|
static InlinedExactClassProfile |
inline(InlineSupport.InlineTarget target)
Returns an inlined version of the profile.
|
abstract <T> T |
profile(T value) |
clone
public abstract <T> T profile(T value)
public static ValueProfile createClassProfile()
Returns a value profile that profiles the exact class of a value. It will check the class of
the profiled value and provide additional information to the compiler if only non-null values
of exactly one concrete Java class are passed as a parameter to the
ValueProfile.profile(T)
method. This can be beneficial if subsequent code can take
advantage of knowing the concrete class of the value. The profile will degrade to the generic
case if a null value or if at least two instances of two different Java classes are
registered.
Compilation notes: Value profiles require a runtime check in their initialized state to verify their profiled class. If two classes have been seen on a single profile instance then this profile will transition to a generic state with no overhead.
usage example
public static ValueProfile create()
Returns a value profile that profiles the exact class of a value. It will check the class of
the profiled value and provide additional information to the compiler if only non-null values
of exactly one concrete Java class are passed as a parameter to the
ValueProfile.profile(T)
method. This can be beneficial if subsequent code can take
advantage of knowing the concrete class of the value. The profile will degrade to the generic
case if a null value or if at least two instances of two different Java classes are
registered.
Compilation notes: Value profiles require a runtime check in their initialized state to verify their profiled class. If two classes have been seen on a single profile instance then this profile will transition to a generic state with no overhead.
usage example
public static ValueProfile createIdentityProfile()
Returns a value profile that profiles the object identity of a value. A single instance can only profile one particular instance.
Compilation notes: Identity profiles require a runtime check to verify their profiled object identity. If two identities have been seen on a single profile instance then this profile will transition to a generic state with no overhead.
public static ValueProfile getUncached()
public static InlinedExactClassProfile inline(InlineSupport.InlineTarget target)