Chapter 9 (#66)

* chapter9

* merge fixes to chapter8

* Ch 9 notes

* Ch 9 work

Add a Iterate phase, after parsing.
Add a Worklist with fast dup removal & rand pull.
Add a Node.iter() call which returns progress or null.  Peephole calls it.  Iter() also asserts that Types make monotonic progress.
Intern all types, so we can do a cheap/easy "isa" test.

* GVN

* rename temporarily

* Apply Cliff's worklist changes

* Apply Cliff's GVN changes

* Revert "GVN"

This reverts commit 9dc6db1cac7e40de4a58333cbc3c9c3e7c088e6f.

* Revert "Ch 9 work"

This reverts commit df5b74e6c017a4f237a5d1a550a83b40a7928876.

* Fix 3-1+2

Was computing as 3-(1+2) == 0, not 4 as expected.
Add tests.
Unlock in swap12.

* Missed some cut-n-paste changes

* Break up the test file per-chapter

* Fix keep-alive while looping expressions

Must "hook" LHS prior to calling peepholes

* Ch9 Region optimization

Bug fix, GVN hits 2 inProgress Loops
Bug fix lifetime tracking when parsing dead code
Bug fix debug find call
GraphViz post-iterate

* Readme overhaul

Progress on Ch 9 readme

* Fix bugs hashcode

Was relying on label() hashCode for Phi, Proj; since this is debug-only cannot be relied on.  Proj relies on _idx field, Phi needs a !inProgress check.

* Constant nodes print "#" before con

* Add a farther neighbor check

Peeps that check more than the nearest neighbor register a dependency on the Node that failed them.  Should that Node later change, the peep root is put back on the worklist and revisited.

* Fix addDeps assert

Unwind golden test print, print smarter.
Unlock edges in subsume

* Update README

* shuffle adddeps forward one

its needed again shortly in another test, so just cover it now

* Fix fuzzer bugs

Peep x+(-y) to x-y
Handle TOP inputs; didn't think it could happen before running an optimistic pass, but fuzzer proved me wrong.
Deleting an input can recursively delete the self-node.
When checking the compute() type assert, delay setting _type so the method can just be re-run in the debugger.
Missing addDep in Phi
Parser mis-handling stacked operators like "1+-2" or "1==!=<=<>=>2"
Make Work list deterministic between tests.

* Update fuzzer to run iterate (#62)

* Update fuzzer to run iterate

* Work seed is now reset by reset

* A few more fuzzer tests

Set _type in iter() even later, better debugging.
Handle dead active scopes in visiualizer.
Region ideal honors Loop invariants; finish Region ideal for single input; inProgress check is a little tighter.
Type.isConstant is true strictly for lattice centerline constants.  Clean up TypeInteger.
ideaj warning removal

* Fix all fuzzer bugs

iter() does not call peep(), instead peep() is self-recursive.  This allows Iterate() to call iter(), and not get into arbitrary recursive peep() changes that do not track on the worklist.
Div, Minus, If all monotonic.
Catch a bunch of progress issues.
Robustify IRPrinter and Iterate and Region ideal

* Reducer could run into an infinite loop (#63)

* Write up how the Evaluator works (#64)

* Write up how the Evaluator works

* Some small improvements and a slightly better wrap up.

* Series of fuzzer bugs.

Fix monotonicity for all data nodes.
Generic compute intercept for data nodes, check all inputs for TOP/BOTTOM, and again for IntDataNodes.
Fix general progress bug allow high Types as constants.
Fix progress Region 1-input has obvious idom.
Make shortcut for fuzzer; renames Fuzzer to not have "Test" in the class name.
Fix invert comment in TypeInteger

* All fuzzer tests pass

Turn off expensive assert accidentally turned on
CSE needs to join types.
Add a type join.
Missing dep in Phi

* More README

* Hacking alternative way to fix the type compute

* Node is no longer IntSupplier
Renamed Work to WorkList
Renamed Iterate to IterOptim
Renamed Node.iter() to Node.peepholeOpt()
WorkList expects elements to be of Node

* Add an example of GVN

* Rename the method depsClear to moveDepsToWorklist - to better capture what it actually does.

* Add a second example of GVN benefits

* Fix typo

* Add example of worklist opt

* Prepare to allow alternative post parse worklist opt

* Alternative WorkList opt that has following differences:
1. It does not require dependencies between nodes
2. It does not require calls from inside the Node class, and therefore runs totally independently as a post parse step.
3. It is simple

* Alternative WorkList opt that has following differences:
1. It does not require dependencies between nodes
2. It does not require calls from inside the Node class, and therefore runs totally independently as a post parse step.
3. It is simple

* The RPO list was incomplete as it only identified the subgraph accessible from the STOP node.

* Fix iter count

* Add test suggested by Xmilia

* Fix bug where after the region is peeped the phis get consistent number of inputs

* Fix bug where after the region is peeped the phis get consistent number of inputs

* Dump out stats on how many nodes we peepd during the post parse iterative opt.

* Make it easy to switch the IterOpt

* Use deps based worklist by default

* Sharper worklist add

* Copy across Cliff's changes

* Merge changes to Iterate

* Revert failing change

* Update readme

* Add comments / update docs to explain the patterns where we call addDep().

* As before, unconditionally made dep a dependent of region.

* Fix a lot of missing dep issues

Rename IterOptim -> IterPeeps
Some grammar changes in comments & readme

* Bump up fuzzer limits, more testing

Missing dep in idom calc in IfNode.
Missed idom cache clear on Region edit.

* Remove RPO based peeps

O(n^2) behavior

* Minor updates README

* fix compile bug

---------

Co-authored-by: Cliff Click <cliffc@acm.org>
Co-authored-by: XmiliaH <45106915+XmiliaH@users.noreply.github.com>
Co-authored-by: Darrick Wiebe <darrickw@untether.ai>

1 files changed, 46 insertions, 1 deletions

diff --git a/chapter08/README.md b/chapter08/README.md
index 402d487a..6d5ce026 100644
--- a/chapter08/README.md
+++ b/chapter08/README.md
@@ -248,4 +248,49 @@ return arg;
 
 ## Sea of Nodes Graph Evaluator
 
-TODO
\ No newline at end of file
+The evaluator directly evaluates the given graph by walking forward through the control flow from the program start until it either encounters a Return node or it passes the maximum loop count.
+
+When called, the evaluator sets itself up by first traversing the graph to find the Start node. Then, if a program uses the special `arg` parameter, the passed-in parameter value will be bound to the node that represents it.
+
+With that brief setup done, the control projection from the Start node is traversed and the program can begin "execution".
+
+At this point, control flow is at the first region of the program, but it is treated just the same as any other region. There are two things that must be done at each region. First, resolve all phis to a specific value; and second to determine where control flow will continue to.
+
+It may seem like more than that should be done, but by resolving phi nodes, any logic that is specific to the control flow path for the given will be resolved. Any other work will eventually be resolved later on as-needed. This is sufficient for the program to run!
+
+Finding the next place control flow will move to after a region is straightforward because any region only has a single control node that uses it. So we search for that node in the Region's users.
+
+Once we have that node, our behavior depends on what type of control flow node we've landed on. There are only 3 options: `RegionNode`, `IfNode`, and `ReturnNode`. If it is another `RegionNode`, we do the same again. If it's a `ReturnNode`, we can resolve the returned expression and return the program's value. Finally, for an `IfNode`, we must first resolve the test expression so that we can choose the false (projection 0) or true (projection 1) branch. Whichever projection from the `IfNode` is chosen, we step through that projection on to the control node (a `RegionNode`) that uses it.
+
+We talk about resolving nodes above, but what does that mean? A node will either have a value (for instance a constant), will already be resolved with the resolved value cached, or it will operate on nodes that it uses, which must be resolved. Once a node's inputs are resolved, its operation may be performed on them. For instance, an `AddNode`'s value will be the sum of its two inputs. Once the value is resolved, the resolved value is returned.
+
+With that, a simple non-looping program can be evaluated.
+
+Looping is almost functional with that, too, with only a couple of small extra details. Whenever control moves through a `LoopNode`, the evaluator checks that it hasn't run out of loop iterations. If it has, a timeout RuntimeException will be thrown. 
+
+Finally, while calculating the value of `PhiNode`s in the loop region, we must be careful to compute all of their new values before we update any of their cached values. That's because as a loop iterates, we must ensure that all `PhiNode` values are consistently the value from the same point in time. Once all of the new values are calculated, we can update the cache for all of them at once. To illustrate this, consider the following code:
+
+```java
+t = 0;
+while(arg < 10) {
+    t = arg;
+    arg = arg + 1;
+}
+return t;
+```
+
+In this code, the two statements within the loop may be evaluated in either order by the graph, so we must ensure that the new value `arg` is not cached before the value of `t` can be set to the previous value of `arg`.
+
+This approach to evaluation is useful for testing because it allows a program to be executed without worrying about instruction selection, register allocation or code generation. It can execute on any valid Sea of Nodes graph, as well, so execution results of unoptimized code can be checked against the results of optimized code! This fact lends itself to some interesting automated / regression testing ideas. For instance, the result of execution could be checked after every optimization step, possibly helping isolate some types of errors.
+
+``` java
+arg=arg+arg;
+arg=arg+arg;
+...
+arg=arg+arg;
+return arg;
+```
+
+On the other hand, this engine is not designed to be particularly fast! Because not all expressions are cached, it's possible to construct programs like the preceeding one which have exponential runtime.
+
+