The "Long polling example" is unclear

[holyjak]

From the (Long polling example)[http://http-kit.org/server.html#polling] it would seem that the on-some-event function is blocking. However I do not believe that is the case, I believe the request should return immediatelly and then later something should send! the data. So instead of

(defn handler [request]
  (with-channel request channel
    (on-some-event ;; wait for event
     (send! channel {:status 200
                     :headers {"Content-Type" "application/json; charset=utf-8"}
                     :body "polling result"}
        ; send! and close. just be explicit, true is the default for streaming/polling,
                    true))))

we should perhaps have something like this:

(defn handler [request]
  (with-channel request channel
     ;; Either trigger asynchronous delivery of the response to the channel (below)
     ;; or make the channel available to other threads to send! to it
    (future
      (when-some-event-happens-do ;; your even awaiting function (blocking)
        (send! channel {:status 200
                       :headers {"Content-Type" "application/json; charset=utf-8"}
                       :body "polling result"}
          ; send! and close. just be explicit, true is the default for streaming/polling,
                      true))))

[shenfeng]

Yeah, the comment "wait for event" make it worse. My initial thought was on-some-event just register a callback, and returns immediately. Maybe I should come up a better name, and fix the comment.

You suggestion of the future and blocking wait, if is real code, need one dedicated thread for one client, which make it not ideal for Clojure(not scalable). One example is something like this: https://github.com/http-kit/chat-polling/blob/master/src/main.clj#L39

[holyjak]

Good point! Let me give it another try.

[holyjak]

What do you think about this one?

(defn handler [request]
  (with-channel request channel
    ;; Create & somehow store a callback for later invocation 
    ;; Ex.: given (def callbacks (atom nil)), call (swap! callbacks conj callback)
    (my-register-callback
      (fn [data]
        (send! channel {:status 200
                       :headers {"Content-Type" "application/json; charset=utf-8"}
                       :body data}
          ; send! and close. just be explicit, true is the default for streaming/polling,
                      true))))
;;; At some other place/thread, when the data has been made available:
;;; (doseq [callback @callbacks] (callback data) (swap! callbacks disj callback))

[shenfeng]

Looks good. Thanks!

I will try to update to update the documentation later when I get home from work. And add the links and update the sample code as you mentions in https://github.com/http-kit/chat-polling/pull/1#issuecomment-20103205

I am not a native English speaker. So, I need sometime to figure out how to document them. Your guys help a lot, and help making the documentation much better.

[shenfeng]

OK, the documentation and example code both get updated.

http://http-kit.org/server.html#polling

Thanks!