 
 ;; -- Router Loop ------------------------------------------------------------
 ;;
-;; A call to "re-frame.core/dispatch" places an event on a queue.  Sometime
-;; shortly afterwards the associated event handler will be run.  The following
-;; code implements this process.
-;;
-;; So, the task is to process events in a perpetual loop, one after
-;; the other, FIFO, calling the right event-handler for each, being idle when
-;; there are no events, and firing up when one arrives, etc. The processing
-;; of an event happens "asynchronously" sometime after the event is
-;; dispatched.
-;;
-;; In practice, browsers only have a single thread of control and we must be
+;; A call to "re-frame.core/dispatch" places an event on a queue for processing.
+;; A short time later, the handler registered to handle this event will be run.
+;; What follows is the implemtation of this process.
+;;
+;; The task is to process queued events in a perpetual loop, one after
+;; the other, FIFO, calling the registered event-handler for each, being idle when
+;; there are no events, and firing up when one arrives.
+;;
+;; But browsers only have a single thread of control and we must be
 ;; careful to not hog the CPU. When processing events one after another, we
 ;; must hand back control to the browser regularly, so it can redraw, process
 ;; websockets, etc. But not too regularly! If we are in a de-focused browser

;; to process all queued events, or else something like a bursty websocket
;; (producing events) might overwhelm the queue. So there's a balance.
;;
;; The original implementation of this router loop used core.async. It was
;; fairly simple, and it mostly worked, but it did not give enough
;; control. So now we hand-roll our own, finite-state-machine and all.
;;
;; The strategy is this:
;;   - maintain a FIFO queue of `dispatched` events.
;;   - when a new event arrives, "schedule" processing of this queue using
;;     goog.async.nextTick, which means it will happen "very soon".
;;   - when processing events, do ALL the those currently queued. Don't stop.
;;     Don't yield to the browser. Hog that CPU.
;;   - but if any new events are dispatched during this cycle of processing,
;;     don't do them immediately. Leave them queued. Yield first to the browser,
;;     and do these new events in the next processing cycle. That way we drain


(defn dispatch-sync
  "Send an event to be processed by the registered handler
  immediately. Note: dispatch-sync cannot be called while another
  event is being handled.

  Usage example:
