InlinedLoopConditionProfile

java.lang.Object
- com.oracle.truffle.api.profiles.InlinedProfile
- - com.oracle.truffle.api.profiles.InlinedLoopConditionProfile

```
public final class InlinedLoopConditionProfile
extends InlinedProfile
```
InlinedLoopConditionProfiles are designed to profile the outcome of loop conditions. Loop profiles can be used to profile unpredictable loops as well as predictable loops. This profile is intended to be used in combination with Truffle DSL.

Uncounted loop usage example:
```
 class LoopNode extends Node {

     abstract void execute();

     @Specialization
     void doDefault(@Cached InlinedLoopConditionProfile loopProfile) {
         // loop count cannot be predicted
         while (loopProfile.profile(this, Math.random() >= 0.9)) {
             // work
         }
     }
 }
 
```
Counted loop usage example:
```
 class CountedLoopNode extends Node {

     abstract void execute(int length);

     @Specialization
     void doDefault(int length, @Cached InlinedLoopConditionProfile loopProfile) {
         // loop count can be predicted
         loopProfile.profileCounted(this, length);
         for (int i = 0; loopProfile.inject(this, i < length); i++) {
             // work
         }
     }
 }
 
```
The advantage of using InlinedLoopConditionProfile.profileCounted(Node, long) to using InlinedLoopConditionProfile.profile(Node, boolean) is that it incurs less overhead in the interpreter. Using InlinedLoopConditionProfile.inject(Node, boolean) is a no-op in the interpreter while InlinedLoopConditionProfile.profile(Node, boolean) needs to use a counter for each iteration.
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: Inlined profiles are used using the Cached annotation in specialization methods. See the individual profile subclasses for further usage examples. Profiles are intended for local speculation 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 local speculation. 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, ideally based on measurements in real world applications.
Footprint: Inlined versions of profiles have a significantly reduced memory footprint compared to their allocated counterparts, however they do rely on their usage being inlined to have the same performance characteristics. 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.
Inlined profile subclasses:
- InlinedBranchProfile to profile on unlikely branches like errors.
- InlinedConditionProfile to profile on conditionals or boolean values.
- InlinedCountingConditionProfile to profile on conditionals or boolean values using counters.
- InlinedLoopConditionProfile to profile on conditionals of loops with special support for counted loops.
- InlinedByteValueProfile to profile on byte values.
- InlinedIntValueProfile to profile on int values.
- InlinedLongValueProfile to profile on long values.
- InlinedFloatValueProfile to profile on float values.
- InlinedDoubleValueProfile to profile on double values.
Since:

23.0

See Also:

InlinedConditionProfile, InlinedCountingConditionProfile, LoopConditionProfile

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`disable(Node node)` Disables this profile by setting it to its generic state.
`static InlinedLoopConditionProfile`	`getUncached()` Returns the uncached version of the profile.
`boolean`	`inject(Node node, boolean condition)` Provides an alternative way to profile counted loops with less interpreter footprint.
`static InlinedLoopConditionProfile`	`inline(InlineSupport.InlineTarget target)` Returns an inlined version of the profile.
`boolean`	`profile(Node node, boolean condition)`
`void`	`profileCounted(Node node, long length)` Provides an alternative way to profile counted loops with less interpreter footprint.
`void`	`reset(Node node)` Resets this profile to its uninitialized state.
`String`	`toString(Node node)` Prints a string representation of this inlined profile given a target node.
`boolean`	`wasFalse(Node node)` Returns `true` if the `InlinedLoopConditionProfile.profile(Node, boolean)` method ever received a `false` value, otherwise `false`.
`boolean`	`wasTrue(Node node)` Returns `true` if the `InlinedLoopConditionProfile.profile(Node, boolean)` method ever received a `true` value, otherwise `false`.

Methods inherited from class com.oracle.truffle.api.profiles.InlinedProfile
toString

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - profile
```
public boolean profile(Node node,
                       boolean condition)
```
    Since:
    
    23.0
  - profileCounted
```
public void profileCounted(Node node,
                           long length)
```
    Provides an alternative way to profile counted loops with less interpreter footprint. Please see InlinedLoopConditionProfile for an usage example.
    
    Since:
    
    23.0
    
    See Also:
    
    InlinedLoopConditionProfile.inject(Node, boolean)
  - inject
```
public boolean inject(Node node,
                      boolean condition)
```
    Provides an alternative way to profile counted loops with less interpreter footprint. Please see InlinedLoopConditionProfile for an usage example.
    
    Since:
    
    23.0
  - wasTrue
```
public boolean wasTrue(Node node)
```
    Returns true if the InlinedLoopConditionProfile.profile(Node, boolean) method ever received a true value, otherwise false. For profiles with profiling disabled or uncached profiles this method always returns true.
    
    Since:
    
    23.0
  - wasFalse
```
public boolean wasFalse(Node node)
```
    Returns true if the InlinedLoopConditionProfile.profile(Node, boolean) method ever received a false value, otherwise false. For profiles with profiling disabled or uncached profiles this method always returns true.
    
    Since:
    
    23.0
  - disable
```
public void disable(Node node)
```
    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.
    
    Specified by:
    
    disable in class InlinedProfile
    
    Since:
    
    23.0
  - reset
```
public void reset(Node node)
```
    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.
    
    Specified by:
    
    reset in class InlinedProfile
    
    Since:
    
    23.0
  - toString
```
public String toString(Node node)
```
    Prints a string representation of this inlined profile given a target node.
    
    Specified by:
    
    toString in class InlinedProfile
    
    Since:
    
    23.0
  - inline
```
public static InlinedLoopConditionProfile inline(InlineSupport.InlineTarget target)
```
    Returns an inlined version of the profile. This version is automatically used by Truffle DSL node inlining.
    
    Since:
    
    23.0
  - getUncached
```
public static InlinedLoopConditionProfile getUncached()
```
    Returns the uncached version of the profile. The uncached version of a profile does not perform any profiling.
    
    Since:
    
    23.0

Class InlinedLoopConditionProfile

Method Summary

Methods inherited from class com.oracle.truffle.api.profiles.InlinedProfile

Methods inherited from class java.lang.Object

Method Detail

profile

profileCounted

inject

wasTrue

wasFalse

disable

reset

toString

inline

getUncached