Add comments about instrumentation

Author: msimacek

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/bytecode/PBytecodeRootNode.java

@@ -508,6 +508,10 @@ public final class PBytecodeRootNode extends PRootNode implements BytecodeOSRNod
      */
     @CompilationFinal(dimensions = 1) private byte[] variableTypes;
 
+    /*
+     * When instrumentation is in use, InstrumentationSupport#bciToHelper node is used instead of
+     * this array. Use getChildNodes() to get the right array.
+     */
     @Children private final Node[] adoptedNodes;
     @Child private CalleeContext calleeContext = CalleeContext.create();
     @Child private PythonObjectFactory factory = PythonObjectFactory.create();

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/bytecode/instrumentation/InstrumentationRoot.java

@@ -45,6 +45,12 @@
 import com.oracle.truffle.api.instrumentation.StandardTags;
 import com.oracle.truffle.api.instrumentation.Tag;
 
+/**
+ * Takes care of lazily materializing the instrumentation nodes when requested. Also its wrapper is
+ * notified of entering and exiting the function.
+ *
+ * @see InstrumentationSupport
+ */
 @GenerateWrapper
 public abstract class InstrumentationRoot extends InstrumentedBytecodeNode {
     public static InstrumentationRoot create() {

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/bytecode/instrumentation/InstrumentationRootImpl.java

@@ -48,6 +48,10 @@
 import com.oracle.truffle.api.instrumentation.Tag;
 import com.oracle.truffle.api.source.SourceSection;
 
+/**
+ * @see InstrumentationRoot
+ * @see InstrumentationSupport
+ */
 class InstrumentationRootImpl extends InstrumentationRoot {
 
     @Child private volatile InstrumentationSupport instrumentationSupport;

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/bytecode/instrumentation/InstrumentationSupport.java

@@ -52,9 +52,24 @@
 import com.oracle.truffle.api.instrumentation.ProbeNode;
 import com.oracle.truffle.api.nodes.Node;
 
+/**
+ * The bytecode interpreter has no AST nodes therefore Truffle AST instrumentation doesn't directly
+ * work. We work around that by lazily creating a fake non-executable AST with a list of statement
+ * nodes. We keep track of line changes in the bytecode loop and notify the probe nodes manually. We
+ * also insert bytecode helper nodes into the statement nodes so that asking the location of a call
+ * node obtained from a frame works.
+ *
+ * @see InstrumentationRoot
+ */
 public final class InstrumentationSupport extends Node {
     final CodeUnit code;
     @Children InstrumentedBytecodeStatement[] lineToNode;
+    /*
+     * When instrumentation is active, this array is used instead of PBytecodeRootNode#adoptedNodes
+     * to hold helper nodes. The actual helper nodes are adopted by the statement nodes in
+     * lineToNode, so this must not be annotated as @Children. When materializing, we cannot reuse
+     * existing nodes from adoptedNodes due to possible race conditions.
+     */
     @CompilationFinal(dimensions = 1) public Node[] bciToHelperNode;
 
     public InstrumentationSupport(PBytecodeRootNode rootNode) {