Recently I watched a talk by David Nolen about Clojure's core.async library. For anyone who wanting to learn about core.async, this talk is a great place to start.
In the talk David demonstrated a process function that used one channel as a control, to turn off and on output on another channel. He did not have time to go into detail about how it worked, so I wanted to build something with it to make sure I understood it.
A pair of chess clocks is a system that has two processes that are turned off and on by pushing buttons. I used Om for the rendering. You can see the complete code on github.
The operation of each clock is represented by a function called counter. It takes an om cursor with the time it will be counting and a control channel which turns the counter off and on.
(defn counter [app control]
(go
(loop [clock-state (cycle [:off :on])]
(do
(let [t (timeout 1000)
[v c] (alts! [t control])]
(cond
(and (= (first clock-state) :on)
(= c t))
(do
(om/transact! app :time minus-sec)
(recur clock-state))
(and (= (first clock-state) :off)
(= c control)
(= v :start))
(recur (next clock-state))
(and (= (first clock-state) :on)
(= c control)
(= v :stop))
(recur (next clock-state))
(and (= c control)
(= v :end))
(.log js/console "game over")
:else
(recur clock-state)))))))
Each time through the loop the function listens on the control channel and also sets a timeout for 1 second. If there is a message on the control channel, the clock state is adjusted and the loop repeats. If a timeout occurs and the clock is on, om/transact! is called to subtract a second from the cursor. If the timeout occurs when the clock is not on, then it repeats the loop without subtracting the second. If there is an :end message in the control channel, then the loop exits.
The UI for each clock is defined in the clock-view function. As an om component it gets its state from the cursor passed in as the first argument, but it can also have state passed in an option map by its parent function.
(defn clock-view [app owner]
(reify
om/IWillMount
(will-mount [_]
(let [input (om/get-state owner :input)
ctrl (counter app input)]))
om/IRenderState
(render-state [this {:keys [master]}]
(let [tag (:tag app)]
(dom/div #js {:className "clock"}
(dom/h3 nil (str "Player " (name tag)))
(dom/h3 #js {:className "clockface"} (time->string (:time app)))
(dom/button #js {:onClick
(fn [e] (put! master tag))} "Move"))))))
The local state for the clock view contains two channels. The input channel is used to by the counter function that controls the clock. In om the appropriate place for controls is the IWillMount protocol. The master channel is needed only at rendering time, where it is used in an event handler for the clock’s Move button.
Messages are put onto the control channel for the clocks by the switch-clock function.
(defn switch-clock [tag wc bc msgchan]
(go
(cond
(= tag :white)
(do
(>! wc :stop)
(>! bc :start)
(>! msgchan "Black to move"))
(= tag :black)
(do
(>! wc :start)
(>! bc :stop)
(>! msgchan "White to move"))
(= tag :end)
(do
(>! wc :end)
(>! bc :end)
(>! msgchan "Game over")))))
The possible tags are :white for the button on the white clock being pressed, :black for the button on the black clock and :end. The game can end when either the End Game button is pressed, or when either clock runs out of time.
The parent of the clock views is the board-view function. The board view creates tells the clock-view function where to draw itself and passes each clock its portion of the cursor and creates the component local state with the channels that each component needs for communication.
(defn board-view [app owner]
(reify
om/IInitState
(init-state [_]
{:white-control (chan)
:black-control (chan)
:message (chan)})
om/IWillMount
(will-mount [_]
(let [main (om/get-state owner :main-control)
message (om/get-state owner :message)
wc (om/get-state owner :white-control)
bc (om/get-state owner :black-control)]
(go (loop []
(let [tag (<! main)]
(switch-clock tag wc bc message)
(recur))))
(go (loop []
(let [msg (<! message)]
(om/update! app [:msg] msg)
(recur))))))
om/IRenderState
(render-state [this {:keys [white-control black-control main-control message]}]
(dom/div nil
(dom/h2 #js {:className "header"} "Chess Clocks")
(dom/h3 #js {:className "message"} (:msg app))
(dom/button #js {:onClick
(fn [e] (put! main-control :end))}
"End Game")
(dom/div #js {:className "clocks"}
(om/build clock-view (:white-clock app)
{:init-state {:master main-control
:input white-control}})
(om/build clock-view (:black-clock app)
{:init-state {:master main-control
:input black-control}}))))))
The control channels for the white clock and black clock are created in the IInitState implementation and will be passed to the individual clocks and to the switch clock function. switch-clock also needs a channel to write messages that will be displayed to the user.
The IWillMount function uses a fourth channel, :main-control that is passed in from the root function. The main-control channel is where messages are written when the buttons are clicked or when time runs out. The first go loop listens for messages on the main control channel and sends them to the switch-clock function. The second go loop listens for messages to be displayed to the user.
IRenderState gets a reference to each of the channels it needs. Whether they were created in IInitState or passed in the root function they are contained in the state map.
The main channel gets written to in the event handler for the End Game button. This channel is also passed to the clock-view function, because each clock view contains a button that writes to the channel.
The main-control channel is created outside of the board-view function, because in addition to the buttons on the UI, there is one other event that needs to write to it. When either clock runs out the game needs to end. This is accomplished using the :tx-listen option in the om/root function.
(om/root
board-view
app-state
(let [main (chan)]
{:target (. js/document (getElementById "app"))
:init-state {:main-control main}
:tx-listen (fn [update new-state]
(when (= (:new-value update) {:min 0 :sec 0})
(put! main :end)))}))
:tx-listen allows you to specify a function that will be called whenever the root app-state changes. The function takes two arguments. The first contains information about the update, with tags :path, :old-value :new-value, :old-state and :new-state. The second parameter is the cursor in its new state.
In this case, I check the new value in the update to see if the time has run out, so that I can end the game.
One problem I had that I want to call attention to is the difference between a map and a cursor. Within the render phase of a function, app is effectively a map, and the data elements can be accessed with the appropriate key. Outside of the render phase, the values inside of the cursors are available only after dereferencing the cursor.
Om's introductory tutorial explicitly calls attention to the fact that outside of the render phase you have to deref the cursor, but in an earlier version of my code I had a go loop, inside of a let, inside of a function, that was called by a component; and I had trouble keeping straight whether I was using a cursor or its data on any given line.
I did not play with it enough to give a detailed explanation, but hopefully just being aware of the issue can save you some debugging time.
