 
 
 ;; ---------------------------------------------------------------------------
-;; This is the global queue for events
-;; When "dispatch" is called, the event is put into this queue.  Later the queue
-;; will "run" and the event will be "handled" by the registered event handler.
+;; Event Queue
+;; When "dispatch" is called, the event is added into this queue.  Later the queue
+;; will "run" and the event will be "handled" by the registered function.
 ;;
 (def event-queue (->EventQueue :idle  #queue [] []))
 


;; -- 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
;; 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


(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:
