h1. evdispatch

<h4 style="float:right;padding-right:10px;">&#x2192; &#8216;evdispatch&#8217;</h4>


h2. What

A library for making HTTP requests in parallel. 

h2. Installing

<pre syntax="ruby">sudo gem install evdispatch</pre>

h2. The basics


The library provides an interface to a background <a href="http://en.wikipedia.org/wiki/POSIX_Threads">posix thread</a> 
running a <a href="http://software.schmorp.de/pkg/libev.html">libev</a> event loop.
HTTP requests are processed using <a href="http://curl.haxx.se/">libcurl</a> and it's <a href="http://curl.haxx.se/libcurl/c/libcurl-multi.html">multi interface</a>.
From Ruby requests and responses are passed back and forth to the event loop
thread using a synchronized queue.  In the future, responses may be processed
in ruby by monitoring a file handle, making it possible to use IO.select.


The intended use of this library was to provide a method for
web applications to make multiple concurrent to satisify a single request.


For example in rails this might look like:

<pre syntax="ruby">

  class DashController < ApplicationController
    def index
      @blogs_id = $dispatcher.request_http("http://10.0.6.45/service/blogs")
      @news_id = $dispatcher.request_http("http://10.0.6.45/service/news")
      @messages_id = $dispatcher.request_http("http://10.0.6.45/service/messages")
    end
  end

  index.html.erb
  <% blogs = JSON.parse($dispatcher.response(@blogs_id)[:body]) %>
  <ul>
  <% for b in blogs %>
    <li><a href="<%= b['link'] %>" ><%= b['title'] %></a></li>
  <% end %>
  </ul>
  <% news = JSON.parse($dispatcher.response(@news_id)[:body]) %>
  <ul>
  <% for n in news %>
    <li><a href="<%= n['link'] %>" ><%= n['title'] %></a></li>
  <% end %>
  </ul>
</pre>


What's interesting is if the blogs response is not back and it blocks on $dispatcher.response(@blogs_id)
chances are high that the news_id will have returned it's response 
by the time it gets finished with the blogs. This is because the background thread does not block while ruby waits for the first response.
One thing to keep in mind is the background thread will block if it has to resolve DNS names.

h2. Demonstration of usage

<pre syntax="ruby">
require 'rubygems'
require 'evdispatch'

# create a new dispatch loop
d = Evdispatch::Loop.new

# start the event loop thread
d.start

# send a dispatch http request and store a handle to the request
google_id = d.request_http("http://www.google.com/")

# do some processing and later on check for the response
response = d.response( google_id )

puts response[:response_time]
puts response[:body]

# sometime later you can stop the event loop
d.stop
</pre>


h2. Forum

"http://groups.google.com/group/evdispatch":http://groups.google.com/group/evdispatch

h2. How to submit patches

Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.

The trunk repository is <a href="http://evdispatch.rubyforge.org/svn/trunk/">http://evdispatch.rubyforge.org/svn/trunk</a> for anonymous access.

h2. F.A.Q.

<ul>
<li><h5> I get an error when installing the gem: <strong>"error: 'curl_socket_t' has not been
  declared"</strong></h5>
  <p> You need to have at least version 7.16 of <a href="http://curl.haxx.se/download.html">libcurl</a>.  I recommend at least version: 7.18.1.</p>
</li>
</ul>

h2. License

This code is free to use under the terms of the MIT license. 

h2. Contact

Comments are welcome. See the "forum":http://groups.google.com/group/evdispatch