com.oracle.truffle.api.profiles

Class ByteValueProfile

java.lang.Object

com.oracle.truffle.api.nodes.NodeCloneable

com.oracle.truffle.api.profiles.Profile

com.oracle.truffle.api.profiles.ByteValueProfile

All Implemented Interfaces:

Cloneable

public final class ByteValueProfile
extends Profile

Specialized value profile to capture certain properties of byte 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 values are profiled within a single profile then the profile has no effect. If the value assumption is invalidated in compiled code then it is invalidated.

Usage example:

class ByteProfileNode extends Node {

    final ByteValueProfile profile = ByteValueProfile.create();

    byte execute(byte input) {
        byte profiledValue = profile.profile(input);
        // compiler may know now more about profiledValue
        return profiledValue;
    }
}

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.

Since:

0.10

See Also:

ByteValueProfile.createIdentityProfile(), ValueProfile

Method Summary

Modifier and Type	Method and Description
static ByteValueProfile	create() Returns a value profile that profiles the exact value of a byte.
static ByteValueProfile	createIdentityProfile() Returns a value profile that profiles the exact value of a byte.
void	disable() Disables this profile by setting it to its generic state.
static ByteValueProfile	getUncached() Returns the uncached version of the profile.
static InlinedByteValueProfile	inline(InlineSupport.InlineTarget target) Returns an inlined version of the profile.
byte	profile(byte value)
void	reset() Resets this profile to its uninitialized state.
String	toString()

Methods inherited from class com.oracle.truffle.api.nodes.NodeCloneable

clone

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

profile

public byte profile(byte value)

Since:

0.10

disable

public void disable()

Disables this profile by setting it to its generic state. After disabling it is guaranteed to never deoptimize on any invocation of a profile method.

This method must not be called on compiled code paths. Note that disabling the profile will not invalidate existing compiled code that uses this profile.

Overrides:

disable in class Profile

Since:

22.1

reset

public void reset()

Resets this profile to its uninitialized state. Has no effect if this profile is already in its uninitialized state or a disabled version of this profile is used.

This method must not be called on compiled code paths. Note that disabling the profile will not invalidate existing compiled code that uses this profile.

Overrides:

reset in class Profile

Since:

22.1

toString

public String toString()

Overrides:

toString in class Object

Since:

22.1

createIdentityProfile

public static ByteValueProfile createIdentityProfile()

Returns a value profile that profiles the exact value of a byte.

Since:

0.10

See Also:

ByteValueProfile

create

public static ByteValueProfile create()

Returns a value profile that profiles the exact value of a byte.

Since:

22.1

See Also:

ByteValueProfile

getUncached

public static ByteValueProfile getUncached()

Returns the uncached version of the profile. The uncached version of a profile does nothing.

Since:

19.0

inline

public static InlinedByteValueProfile inline(InlineSupport.InlineTarget target)

Returns an inlined version of the profile. This version is automatically used by Truffle DSL node inlining.

Since:

23.0