improve comments in Context.java

diff --git a/src/edu/berkeley/fleet/ir/Context.java b/src/edu/berkeley/fleet/ir/Context.java
index ac43956..2aba237 100644 (file)
--- a/src/edu/berkeley/fleet/ir/Context.java
+++ b/src/edu/berkeley/fleet/ir/Context.java
@@ -18,10 +18,26 @@ import static edu.berkeley.fleet.util.BitManipulations.*;
 /**
  *  A Context is a collection of Loops which obey these rules:
  *
- *    - There is a designated entry point loop which is invoked when the Context is loaded
- *    - Loops in a Context may only invoke other Loops in the same Context
- *    - A Context has exclusive control of all docks mentioned by any of its Loops
- *    - A Context does not exit until all of its Loops have exited.
+ *    - A Context has exclusive control of all docks mentioned by any of its Loops.
+ *    - A Context includes a "starting loop" for every dock it mentions.
+ *    - When a Context is spawned, it starts the "starting loop" on all of its docks.
+ *    - A loop may or may not have a successor.
+ *    - Control may transfer only two ways:
+ *        - If a loop has a successor, control will transfer to the successor when the loop finishes.
+ *        - A loop may explicitly transfer control to another loop via abortAndInvoke().  The
+ *          invoked loop must belong to the same Dock and the same Context.
+ *    - A Context finishes when all of its docks have finished executing a loop with no successor.
+ *
+ *  Definitions:
+ *    - A Move instruction is a blocking instruction if either its   tokenIn or dataIn bits are set.
+ *    - All other instructions  are non-blocking.
+ *    - A dock is quiescent if its instruction ring is empty.
+ *    - A dock is pre-quiescent if 
+ *        - all instructions which remain in the target dock's instruction
+ *          fifo are nonblocking instructions,
+ *        - either the docks' OLC=0 or all instructions which remain
+ *          in its instruction fifo are one-shot instructions
+ *        - after executing these remaining instructions, the dock's hatch is open
  */
 public class Context {
 
@@ -218,7 +234,7 @@ public class Context {
         }
 
         // FIXME: what if we're using an ILC-loop?
-        /** abort the loop immediately (if predicate is met) */
+        /** abort the loop immediately (if predicate is met) and invoke the successor loop */
         public void abort() {
             flush_pending();
             instructions.add(new Instruction.Set(dock,
@@ -243,14 +259,8 @@ public class Context {
          *  The code emitted by this method makes the following assumptions:
          *
          *   - The instructions emitted are dispatched in order
-         *   - At the time of dispatch:
-         *       - all instructions which remain in the target dock's instruction fifo are nonblocking instructions
-         *       - either the target docks' OLC=0 or all instructions which remain in its instruction fifo are one-shot instructions
-         *       - after executing these remaining instructions, the target dock's hatch is open
+         *   - At the time of dispatch, the dock must be pre-quiescent.
          *
-         *  A Move instruction is a blocking instruction if either its
-         *  tokenIn or dataIn bits are set.  All other instructions
-         *  are non-blocking.
          */
         public void emit(ArrayList<Instruction> ic) {
             flush_pending();