# HG changeset patch
# User Miguel Garcia
# Date 1399980009 -7200
# Node ID e90ec3e5e45b0c3d526959e3f098213be9c11c9f
# Parent 25ccd455f751de1d32c407626bdcf0d6ee592b2c
[inlining] documentation
diff -r 25ccd455f751 -r e90ec3e5e45b graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/inlining/InliningPhase.java
--- a/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/inlining/InliningPhase.java Tue May 13 16:51:41 2014 +0200
+++ b/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/inlining/InliningPhase.java Tue May 13 13:20:09 2014 +0200
@@ -93,6 +93,68 @@
return inliningCount;
}
+ /**
+ *
+ * The space of inlining decisions is explored depth-first with the help of a stack realized by
+ * {@link InliningData}. At any point in time, its topmost element consist of:
+ *
+ * -
+ * one or more {@link GraphInfo}s of inlining candidates, all of them corresponding to a single
+ * callsite (details below). For example, "exact inline" leads to a single candidate.
+ * -
+ * the callsite (for the targets above) is tracked as a {@link MethodInvocation}. The difference
+ * between {@link MethodInvocation#totalGraphs()} and {@link MethodInvocation#processedGraphs()}
+ * indicates the topmost {@link GraphInfo}s that might be delved-into to explore inlining
+ * opportunities.
+ *
+ *
+ *
+ *
+ * The bottom-most element in the stack consists of:
+ *
+ * -
+ * a single {@link GraphInfo} (the root one, for the method on which inlining was called)
+ * -
+ * a single {@link MethodInvocation} (the {@link MethodInvocation#isRoot} one, ie the unknown
+ * caller of the root graph)
+ *
+ *
+ *
+ *
+ *
+ * The stack grows and shrinks as choices are made among the alternatives below:
+ *
+ * -
+ * not worth inlining: pop any remaining graphs not yet delved into, pop the current invocation.
+ *
+ * -
+ * process next invoke: delve into one of the callsites hosted in the current candidate graph,
+ * determine whether any inlining should be performed in it
+ * -
+ * try to inline: move past the current inlining candidate (remove it from the topmost element).
+ * If that was the last one then try to inline the callsite that is (still) in the topmost
+ * element of {@link InliningData}, and then remove such callsite.
+ *
+ *
+ *
+ *
+ * Some facts about the alternatives above:
+ *
+ * -
+ * the first step amounts to backtracking, the 2nd one to delving, and the 3rd one also involves
+ * bakctraking (however after may-be inlining).
+ * -
+ * the choice of abandon-and-backtrack or delve-into is depends on
+ * {@link InliningPolicy#isWorthInlining} and {@link InliningPolicy#continueInlining}.
+ * -
+ * the 3rd choice is picked when both of the previous one aren't picked
+ * -
+ * as part of trying-to-inline, {@link InliningPolicy#isWorthInlining} again sees use, but
+ * that's another story.
+ *
+ *
+ *
+ */
@Override
protected void run(final StructuredGraph graph, final HighTierContext context) {
final InliningData data = new InliningData(graph, context.getAssumptions());