Context Navigation

Changes between Version 37 and Version 38 of Clojure Client Tutorial

Timestamp:: Aug 8, 2011 11:11:40 AM (13 years ago)
Author:: kedwar10
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

Clojure Client Tutorial

-                      v37
+                      v38
 {{{
 client.core=> (load-quagent)
 :quagent240
+:quagent277
 client.core=> (load-quagent "Bob")
 :Bob
 …
 {{{
 client.core=> (get-quagents)
+(:Bob :quagent240)
+#{:Bob :quagent277}
 }}}
 …
 Note that control of the terminal does not return until the bot has completed his action.
+Now say you want to define a function on the fly to send an op to the server, the easiest way to do so is the 'client->server' function.
+{{{
+client.core=> (doc client->server)
+-------------------------
+client.protocol-one/client->server
+([send-func quagent scheduling op args & fs])
+  Provides a usable interface for sending ops to the server.
+  Arguments are the type of send function, the quagent to
+  execute the op, the scheduling, the op keyword
+  (see *codes* in protocol_one.clj) the arguments to the op
+  (in vector form) and the dispatch functions to be given to
+  the send function.
+nil
+}}}
+The send function can be one of the following
+{{{
+client.core=> (doc send-and-forget)
+-------------------------
+client.protocol-one/send-and-forget
+([quagent id msg])
+  Send an op to the server and throw away the results.
+nil
+}}}
+{{{
+client.core=> (doc send-and-get)
+-------------------------
+client.protocol-one/send-and-get
+([quagent id msg] [quagent id msg f])
+  Send a op to the server and block this thread until the
+  op completes. Args are a (unique) op id, a msg to send
+  to the server and a function f that determines how to
+  combine the current reply from the server with past
+  results (defaults to conj).
+nil
+}}}
+{{{
+client.core=> (doc send-and-get-later)
+-------------------------
+client.protocol-one/send-and-get-later
+([quagent id msg] [quagent id msg f])
+  This will spawn a separate thread to do the send and get,
+  if you try to dereference it before it has completed,
+  it will block.  Use future-done? to check the status before
+  dereferencing.
+nil
+}}}
+{{{
+client.core=> (doc send-and-watch)
+-------------------------
+client.protocol-one/send-and-watch
+([quagent id msg wf] [quagent id msg f wf])
+  Sends the op to the server and then applies f to update the value.
+  When the value changes wf is called (wf must meet the requirements
+  of the add-watch function).  The return value is the key for the
+  watcher; this is used to delete it if necessary
+ [(example)](http://clojure-examples.appspot.com/clojure.core/add-watch?revision=1278516003572).
+nil
+}}}
+Say we want to define a function "get-location-of" that takes one argument (a quagent key) and returns the position as a vector of doubles.
+From protocol zero, we know that the string to be sent to the server should look like "n lc <id>" where <id> is the op id. One possible implementation would be
+{{{
+client.core=> (defn get-location-of
+                [quagent]
+                (client->server send-and-get
+                                quagent
+                                :now
+                                :current-location
+                                nil))
+#'client.core/get-location-of
+}}}
+Note that the protocol zero op codes have been mapped to more user friendly keywords.  Here is the full map (subject to change)
+Now say you want to define a function on the fly to send an op to the server, this can be done with either "send-and-forget", "send-and-get", "send-and-get-later", and "send-and-watch".  These functions provide a human-readable interface to protocol zero by mapping all of the op codes to keywords.  Here is the full list of keyword arguments subject to change).
 * :move-indefinitely "mi"
 * :move-for "mf"
 …
 * :replace "r"
+Running this however, didn't yield the expected output.
+{{{
+client.core=> (get-location-of :Bob)
+[{:data ("-128.000000" "136.000000" "40.125000"), :op "lc", :reply-type "rs", :id "1"}]
+}}}
+Instead of getting a vector of doubles, it returned a vector that contains a map.  To fix this we need to pass in
+an dispatch function to control the behaviour of the return value. This function takes two arguments, the previous
+result, and the most recent reply from the server, and determines how to combine them. For example, say we only
+wish to return the map.
+{{{
+client.core=> (defn get-location-of [quagent]
+                (client->server send-and-get
+                                quagent
+                                :now
+                                :current-location
+                                nil
+                                (fn [prev reply]
+                                  reply)))
+#'client.core/get-location-of
+}}}
+Note the change in return value.
+{{{
+client.core=> (get-location-of :Bob)
+{:data ("-128.000000" "136.000000" "40.125000"), :op "lc", :reply-type "rs", :id "2"}
+}}}
+Here is the correct version. Note the use of destructuring in the anonymous function
+{{{
+client.core=> (defn get-location-of [quagent]
+                (client->server send-and-get
+                                quagent
+                                :now
+                                :current-location
+                                nil
+                                (fn [prev {:keys [data]}]
+                                  (vec (map #(Double/parseDouble %) data)))))
+#'client.core/get-location-of
+}}}
+Now this returns the expected output.
+{{{
+client.core=> (get-location-of :Bob)
+[-128.0 136.0 40.125]
+}}}
+This particular anonymous function is so frequent that that it comes predefined.
+{{{
+client.core=> (defn get-location-of [quagent]
+                (client->server send-and-get
+                                quagent
+                                :now
+                                :current-location
+                                nil
+                                data->doubles))
+#'client.core/get-location-of
+}}}
+Suppose that this particular op took a long time to complete and we didn't want to wait around for it to complete,
+The way clojure handles this is through the use of "futures".  Simply, clojure will do the computation in a separate
+thread so the current one can continue.  send-and-get-later is identitical to send-and-get except that it is passed
+to the "future" function.
+{{{
+client.core=> (doc future)
+-------------------------
+clojure.core/future
+([& body])
+Macro
+  Takes a body of expressions and yields a future object that will
+  invoke the body in another thread, and will cache the result and
+  return it on all subsequent calls to deref/@. If the computation has
+  not yet finished, calls to deref/@ will block.
+nil
+}}}
+We need to redefine "get-location-of" with a different send function.
+{{{
+client.core=> (defn get-location-of [quagent]
+                (client->server send-and-get-later ;
+                                quagent
+                                :now
+                                :current-location
+                                nil
+                                data->doubles))
+#'client.core/get-location-of
+}}}
+Now we need a variable to store the future.
+{{{
+client.core=> (def f (get-location-of :Bob))
+#'client.core/f
+}}}
+In order to check if the computation is done use the "future-done?" function.
+{{{
+client.core=> (doc future-done?)
+-------------------------
+clojure.core/future-done?
+([f])
+  Returns true if future f is done
+nil
+client.core=> (future-done? f)
+true
+}}}
+Now we know f is safe to dereference.
+{{{
+client.core=> @f
+[-128.0 136.0 40.125]
+}}}
+Futures allow us to do more interesting things, however. Say we want to make two bots explore a maze simultaneously,
+this can't be done if the quagents are all blocking on the same thread. Type control-c in the repl and execute the
+following.
+{{{
+client.core=> (run-ioquake "largemaze")
+#<UNIXProcess java.lang.UNIXProcess@5ce40>
+client.core=> (load-quagent :Bob) ; remember to stand in the corner
+:Bob
+client.core=>(make-gui) ; the quagents use a value iteration to calculate the best policy; brightness denotes higher utility
+#<JFrame javax.swing.JFrame (output truncated)>
+client.core=> (def q1 (future (explore-maze :Bob)))
+#'client.core/q1
+client.core=> (load-quagent :Joe)
+:Joe
+client.core=> (def q2 (future (explore-maze :Joe)))
+#'client.core/q2
+}}}
+Suppose now we need a more sophisticated behaviour whereby the quagent sends out a message to the server and then calls a function every
+time the server replies before terminating the op.  This can be accomplished with the last send function "send-and-watch".  Here, an
+additional watcher function (wf) must be specified that takes four arguments: a (k)ey, (r)efernce, (o)ld value, and (n)ew value.
+{{{
+client.core=> (defn get-location-of [quagent]
+                (client->server send-and-watch
+                                quagent
+                                :now
+                                :current-location
+                                nil
+                                (fn [k r o n]
+                                 (println "old val " o " new val " n)))
+#'client.core/get-location-of
+client.core=> (get-location-of :Joe)
+:watcher245
+old val  []  new val  [{:data (64.000000 64.000000 32.125000), :op lc, :reply-type rs, :id 1}]
+}}}
+The key :watcher245 can be used to delete the watch function if so desired.  Otherwise it will be removed when the command completes.
+{{{
+client.core=> (doc remove-watch)
+-------------------------
+clojure.core/remove-watch
+([reference key])
+  Alpha - subject to change.
+  Removes a watch (set by add-watch) from a reference
+nil
+}}}
+Recall that "send-and-watch" can also accept a function to control the combination of previous and current replies as well, so the watcher function argument "o" is not limited to just being a vector of replies.
+{{{
+client.core=> (doc send-and-forget)
+-------------------------
+client.protocol-one/send-and-forget
+([quagent op scheduling args])
+  Sends an op to the server and discards the results.
+  Use the keywords in *codes* (see above) instead of
+  protocol zero codes. The args to the op should be in
+  a vector.
+nil
+}}}
+{{{
+client.core=> (doc send-and-get)
+-------------------------
+client.protocol-one/send-and-get
+([quagent op scheduling args init f])
+  Sends an op to the server and blocks until it returns.
+  Replies are combined using the (init)ial value and
+  (f)unction supplied by the user.   Use the keywords in
+  *codes* (see above) instead of protocol zero codes.
+  The args to the op should be in a vector.
+nil
+}}}
+{{{
+client.core=> (doc send-and-get-later)
+-------------------------
+client.protocol-one/send-and-get-later
+([quagent op scheduling args init f])
+  Sends an op to the server and returns a future
+  that waits for the reply. Replies are combined
+  using the (init)ial value and (f)unction supplied
+  by the user.  Use the keywords in *codes* (see above)
+  instead of protocol zero codes. The args to the op
+  should be in a vector.
+nil
+}}}
+{{{
+client.core=> (doc send-and-watch)
+-------------------------
+client.protocol-one/send-and-watch
+([quagent op scheduling args init f wf])
+  Sends an op to the server and processes replies with
+  an (init)ial value and (f)unction supplied by the user;
+  when the (acc)ulator value changes, wf is called.
+  wf must be a function that accepts 4 arguments,
+  as in (fn [reference key old-val new-val] ...).  Use
+  the keywords in *codes* (see above) instead of protocol
+  zero codes. The args to the op should be in a vector.
+nil
+}}}
+Say we want to define a function "scan-area" that takes two arguments (a quagent key and a radius) and returns a hash map of the positions of the items.
 ----
 …
 == Current Issues ==
 * Exploring the maze with multiple bots will occasionally cause one to hang.  This is not an issue with server since inserting bots via separate repl's fixes the issue.
+* Exploring the maze with multiple bots will occasionally cause one to hang.  This is an issue coordinating multiple data structures in the maze explorer code, not in protocol one.