[commit: hoopl] simonmar-alternative-block-rep: initial commentary on Graph.hs (8959f2e)

[Norman Ramsey]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/hoopl

On branch  : simonmar-alternative-block-rep

http://hackage.haskell.org/trac/ghc/changeset/8959f2e90162630a9244907e60e02b66cd0e64fa

>---------------------------------------------------------------

commit 8959f2e90162630a9244907e60e02b66cd0e64fa
Author: Norman Ramsey <nr at cs.tufts.edu>
Date:   Thu Jun 21 22:34:06 2012 +0200

    initial commentary on Graph.hs

>---------------------------------------------------------------

 src/Compiler/Hoopl/Graph.hs |   17 +++++++++++++++++
 1 files changed, 17 insertions(+), 0 deletions(-)

diff --git a/src/Compiler/Hoopl/Graph.hs b/src/Compiler/Hoopl/Graph.hs
index 3b8ad09..b1464b3 100644
--- a/src/Compiler/Hoopl/Graph.hs
+++ b/src/Compiler/Hoopl/Graph.hs
@@ -47,6 +47,23 @@ data Block n e x where
   BHead   :: Block n O O -> n O O       -> Block n O O
   BTail   :: n O O       -> Block n O O -> Block n O O
 
+-- NR likes this Block representation because the underlying
+-- principles are easy to discern:
+--     
+--
+--   - Fully open blocks are treated as lists of O/O nodes based on the
+--     empty/singleton/append algebra.  This representation gives
+--     append in constant time and allows either front or back bias.
+--     
+--   - Cons and snoc are such common cases that they are included to
+--     reduce the number of indirections in the representations.
+--
+--   - Anywhere a block is closed, the closing node is accessible in
+--     constant time.
+
+
+------------------------------------------------------------------
+
 -- | A (possibly empty) collection of closed/closed blocks
 type Body n = LabelMap (Block n C C)
 newtype Body' block n = Body (LabelMap (block n C C))