org.graalvm.compiler.replacements

Class SnippetTemplate

java.lang.Object

org.graalvm.compiler.replacements.SnippetTemplate

public class SnippetTemplate
extends Object

A snippet template is a graph created by parsing a snippet method and then specialized by binding constants to the snippet's Snippet.ConstantParameter parameters. Snippet templates can be managed in a cache maintained by SnippetTemplate.AbstractTemplates.

Snippet Lowering of WithExceptionNode

Lowering of WithExceptionNode is more complicated than for normal (fixed) nodes, because of the exception edge.

Replacing a WithExceptionNode with a Snippet with an UnwindNode

Replacee Graph

The replacee graph is the graph that contains the node to be lowered and where the snippet graph will be inlined into. In the example below, the WithException node will be lowered via a snippet.

                ...
                 |
                pred
                 |
           WithException  <--- // to be lowered
            /         \
    [next] /           \ [exceptionEdge]
          /             \
       Begin       ExceptionObject
         |              |
     nextSucc      exceptionSucc
         |              |
        ...            ...
 

Snippet Graph

A snippet graph is a complete graph starting with a StartNode and ending with a ReturnNode and or an UnwindNode. For simplicity, multiple ReturnNodes are merged and replaced by a single return node. The following is the simplest possible example for a snippet with an UnwindNode. The snippet consists of an @code InvokeWithException'}.

              Start'
                |
         InvokeWithException'
            /         \
    [next] /           \ [exceptionEdge]
          /             \
       Begin'      ExceptionObject'
         |              |
      Return'        Unwind'
 

Replacee Graph after inlining

After inlining the snippet, the WithException node in the replacee graph is replaced by the snippet graph. The Start' is connected to the predecessor, the Return' to the next edge, and the Unwind' to the exception edge.

                ...
                 |
                pred
                 |
         InvokeWithException'
            /         \
    [next] /           \ [exceptionEdge]
          /             \
       Begin'      ExceptionObject'
         |              |
       Begin       ExceptionObject
         |              |
     nextSucc      exceptionSucc
         |              |
        ...            ...
 

It is important to note that we do not yet remove the original Begin and WithException node, although they are no longer needed. Doing so would require support from the LoweringPhase, which might still hold references to these nodes for subsequent lowering rounds. Simplifications and lowering will take care of removing these nodes.

Replacee Graph after lowering

After the whole replacee graph has been lowered, the superfluous nodes are gone.

                ...
                 |
                pred
                 |
         InvokeWithException'
            /         \
    [next] /           \ [exceptionEdge]
          /             \
       Begin'      ExceptionObject'
         |              |
     nextSucc      exceptionSucc
         |              |
        ...            ...
 

Replacing a non-throwing WithExceptionNode with a Snippet with an UnwindNode

Replacee Graph

Non-throwing WithExceptionNode are nodes where the exception edge is an UnreachableBeginNode followed by an UnreachableControlSinkNode. This pattern is used to encode that we have proven that the WithExceptionNode will never throw an exception.

                ...
                 |
                pred
                 |
           WithException  <--- // to be lowered
            /         \
    [next] /           \ [exceptionEdge]
          /             \
       Begin       UnreachableBegin
         |              |
     nextSucc      UnreachableControlSink
         |
        ...
 

Snippet Graph

The snippet graph is the same as in the example above.

              Start'
                |
         InvokeWithException'
            /         \
    [next] /           \ [exceptionEdge]
          /             \
       Begin'      ExceptionObject'
         |              |
      Return'        Unwind'
 

Replacee Graph after inlining

In this case, we remove the ExceptionObject' from the snippet graph, and attach the original UnreachableBegin directly to the exception producing instruction from the snippet (the InvokeWithException' node in this example).

                ...
                 |
                pred
                 |
         InvokeWithException'
            /         \
    [next] /           \ [exceptionEdge]
          /             \
       Begin'      UnreachableBegin
         |              |
       Begin       UnreachableControlSink
         |
     nextSucc
         |
        ...
 

Replacing a WithExceptionNode with a Snippet without an UnwindNode

There are cases where snippets are known not to throw an exception, although the replacee is a WithExceptionNode.

Replacee Graph

Let us reuse the example from the first case.

                ...
                 |
                pred
                 |
           WithException  <--- // to be lowered
            /         \
    [next] /           \ [exceptionEdge]
          /             \
       Begin       ExceptionObject
         |              |
     nextSucc      exceptionSucc
         |              |
        ...            ...
 

Snippet Graph

In this example, the snippet graph consists of a single NonThrowingWork' node.

              Start'
                |
          NonThrowingWork'
                |
             Return'
 

Replacee Graph after inlining

As outlined above, we cannot simply delete the nodes connected to the replacee because it would interfere with the LoweringPhase. Thus, we introduce an artificial PlaceholderWithException' that connects to the exception edge. This placeholder node removes the exception edge and itself in a subsequent canonicalization.

                ...
                 |
                pred
                |
           NonThrowingWork'
                 |
      PlaceholderWithException'
            /         \
    [next] /           \ [exceptionEdge]
          /             \
       Begin'      ExceptionObject'
         |              |
       Begin       ExceptionObject
         |              |
     nextSucc      exceptionSucc
         |              |
        ...            ...
 

Replacee Graph after lowering

After the whole replacee graph has been lowered, the graph looks like the following.

                ...
                 |
                pred
                 |
           NonThrowingWork'
                 |
             nextSucc
                 |
                ...
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SnippetTemplate.AbstractTemplates Base class for snippet classes.
static class	SnippetTemplate.Arguments Values that are bound to the snippet method parameters.
static class	SnippetTemplate.EagerSnippetInfo
protected static class	SnippetTemplate.LazySnippetInfo
static class	SnippetTemplate.SnippetInfo Holds the ResolvedJavaMethod of the snippet, together with some information about the method that needs to be computed only once.
static interface	SnippetTemplate.UsageReplacer Logic for replacing a snippet-lowered node at its usages with the return value of the snippet.

Field Summary

Fields

Modifier and Type	Field and Description
static SnippetTemplate.UsageReplacer	DEFAULT_REPLACER Represents the default usage replacer logic which simply delegates to Node.replaceAtUsages(Node).

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SnippetTemplate(OptionValues options, DebugContext debug, Providers providers, SnippetTemplate.Arguments args, boolean trackNodeSourcePosition, Node replacee, PhaseSuite<Providers> midTierPhases) Creates a snippet template.

Method Summary

Modifier and Type	Method and Description
StructuredGraph	copySpecializedGraph(DebugContext debugForCopy) Gets a copy of the specialized graph.
static void	explodeLoops(StructuredGraph snippetCopy, CoreProviders providers)
protected JavaConstant	forBoxed(Object argument, JavaKind localKind) Converts a Java boxed value to a JavaConstant of the right kind.
protected Object[]	getConstantArgs(SnippetTemplate.Arguments args)
Node	getReturnValue(org.graalvm.collections.UnmodifiableEconomicMap<Node,Node> duplicates)
boolean	hasSideEffects()
org.graalvm.collections.UnmodifiableEconomicMap<Node,Node>	instantiate(MetaAccessProvider metaAccess, FixedNode replacee, SnippetTemplate.UsageReplacer replacer, SnippetTemplate.Arguments args) Replaces a given fixed node with this specialized snippet.
org.graalvm.collections.UnmodifiableEconomicMap<Node,Node>	instantiate(MetaAccessProvider metaAccess, FixedNode replacee, SnippetTemplate.UsageReplacer replacer, SnippetTemplate.Arguments args, boolean killReplacee) Replaces a given fixed node with this specialized snippet.
void	instantiate(MetaAccessProvider metaAccess, FloatingNode replacee, SnippetTemplate.UsageReplacer replacer, LoweringTool tool, SnippetTemplate.Arguments args) Replaces a given floating node with this specialized snippet.
void	instantiate(MetaAccessProvider metaAccess, FloatingNode replacee, SnippetTemplate.UsageReplacer replacer, SnippetTemplate.Arguments args) Replaces a given floating node with this specialized snippet.
static void	replaceExceptionObjectNode(AbstractBeginNode originalExceptionEdge, FixedWithNextNode replacementUnwindPath) Replaces the original ExceptionObjectNode with the exception handling path from the snippet.
protected void	rewireFrameStates(ValueNode replacee, org.graalvm.collections.UnmodifiableEconomicMap<Node,Node> duplicates, FixedNode replaceeGraphCFGPredecessor)
void	setMayRemoveLocation(boolean mayRemoveLocation)
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_REPLACER

public static final SnippetTemplate.UsageReplacer DEFAULT_REPLACER

Represents the default usage replacer logic which simply delegates to Node.replaceAtUsages(Node).

Constructor Detail

SnippetTemplate

protected SnippetTemplate(OptionValues options,
                          DebugContext debug,
                          Providers providers,
                          SnippetTemplate.Arguments args,
                          boolean trackNodeSourcePosition,
                          Node replacee,
                          PhaseSuite<Providers> midTierPhases)

Creates a snippet template.

Method Detail

explodeLoops

public static void explodeLoops(StructuredGraph snippetCopy,
                                CoreProviders providers)

getConstantArgs

protected Object[] getConstantArgs(SnippetTemplate.Arguments args)

hasSideEffects

public boolean hasSideEffects()

forBoxed

protected JavaConstant forBoxed(Object argument,
                                JavaKind localKind)

Converts a Java boxed value to a JavaConstant of the right kind. This adjusts for the limitation that a Local's kind is a stack kind and so cannot be used for re-boxing primitives smaller than an int.

Parameters:

argument - a Java boxed value

localKind - the kind of the Local to which argument will be bound

getReturnValue

public Node getReturnValue(org.graalvm.collections.UnmodifiableEconomicMap<Node,Node> duplicates)

instantiate

public org.graalvm.collections.UnmodifiableEconomicMap<Node,Node> instantiate(MetaAccessProvider metaAccess,
                                                                              FixedNode replacee,
                                                                              SnippetTemplate.UsageReplacer replacer,
                                                                              SnippetTemplate.Arguments args)

Replaces a given fixed node with this specialized snippet.

Parameters:

metaAccess -

replacee - the node that will be replaced

replacer - object that replaces the usages of replacee

args - the arguments to be bound to the flattened positional parameters of the snippet

Returns:

the map of duplicated nodes (original -> duplicate)

instantiate

public org.graalvm.collections.UnmodifiableEconomicMap<Node,Node> instantiate(MetaAccessProvider metaAccess,
                                                                              FixedNode replacee,
                                                                              SnippetTemplate.UsageReplacer replacer,
                                                                              SnippetTemplate.Arguments args,
                                                                              boolean killReplacee)

Replaces a given fixed node with this specialized snippet.

Parameters:

metaAccess -

replacee - the node that will be replaced

replacer - object that replaces the usages of replacee

args - the arguments to be bound to the flattened positional parameters of the snippet

killReplacee - is true, the replacee node is deleted

Returns:

the map of duplicated nodes (original -> duplicate)

replaceExceptionObjectNode

public static void replaceExceptionObjectNode(AbstractBeginNode originalExceptionEdge,
                                              FixedWithNextNode replacementUnwindPath)

Replaces the original ExceptionObjectNode with the exception handling path from the snippet. Ideally, this should simply be the following:

 graph.replaceFixedWithFixed(originalExceptionEdge, replacementUnwindPath);
 

Unfortunately, removing control flow paths during lowering might confuse the lowering phase. So until this is fixed (GR-34538), instead of deleting the original ExceptionObjectNode, we keep it and insert the new exception handling path just before it. ExceptionObjectNode.lower(org.graalvm.compiler.nodes.spi.LoweringTool) will notice this situation later and delete the node.

Parameters:

originalExceptionEdge - the ExceptionObjectNode that should be deleted

replacementUnwindPath - the replacement for the original ExceptionObjectNode

See Also:

ExceptionObjectNode.lower(org.graalvm.compiler.nodes.spi.LoweringTool)

copySpecializedGraph

public StructuredGraph copySpecializedGraph(DebugContext debugForCopy)

Gets a copy of the specialized graph.

instantiate

public void instantiate(MetaAccessProvider metaAccess,
                        FloatingNode replacee,
                        SnippetTemplate.UsageReplacer replacer,
                        LoweringTool tool,
                        SnippetTemplate.Arguments args)

Replaces a given floating node with this specialized snippet.

Parameters:

metaAccess -

replacee - the node that will be replaced

replacer - object that replaces the usages of replacee

tool - lowering tool used to insert the snippet into the control-flow

args - the arguments to be bound to the flattened positional parameters of the snippet

instantiate

public void instantiate(MetaAccessProvider metaAccess,
                        FloatingNode replacee,
                        SnippetTemplate.UsageReplacer replacer,
                        SnippetTemplate.Arguments args)

Replaces a given floating node with this specialized snippet. This snippet must be pure data-flow

Parameters:

metaAccess -

replacee - the node that will be replaced

replacer - object that replaces the usages of replacee

args - the arguments to be bound to the flattened positional parameters of the snippet

rewireFrameStates

protected void rewireFrameStates(ValueNode replacee,
                                 org.graalvm.collections.UnmodifiableEconomicMap<Node,Node> duplicates,
                                 FixedNode replaceeGraphCFGPredecessor)

toString

public String toString()

Overrides:

toString in class Object

setMayRemoveLocation

public void setMayRemoveLocation(boolean mayRemoveLocation)