Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

switch typhoeus to ffi #151

Merged
merged 11 commits into from
May 15, 2012
Merged
27 changes: 12 additions & 15 deletions README.textile
Original file line number Diff line number Diff line change
Expand Up @@ -14,33 +14,32 @@ h2. Summary

Like a modern code version of the mythical beast with 100 serpent heads, Typhoeus runs HTTP requests in parallel while cleanly encapsulating handling logic. To be a little more specific, it's a library for accessing web services in Ruby. It's specifically designed for building RESTful service oriented architectures in Ruby that need to be fast enough to process calls to multiple services within the client's HTTP request/response life cycle.

Some of the awesome features are parallel request execution, memoization of request responses (so you don't make the same request multiple times in a single group), built in support for caching responses to memcached (or whatever), and mocking capability baked in. It uses libcurl and libcurl-multi to work this speedy magic. I wrote the c bindings myself so it's yet another Ruby libcurl library, but with some extra awesomeness added in.

h2. Windows Support

Windows is tricky to get up and running. A reported working version of curl is "curl-7.19.4-devel-mingw32", provided you point --with-opt-include and --with-opt-lib flags to the correct directory when you `gem install`. Patches to make Windows work seamlessly are welcome!
Some of the awesome features are parallel request execution, memoization of request responses (so you don't make the same request multiple times in a single group), built in support for caching responses to memcached (or whatever), and mocking capability baked in. It uses libcurl and libcurl-multi to work this speedy magic. I wrote the bindings myself so it's yet another Ruby libcurl library, but with some extra awesomeness added in. FFI is used to interface with the library so it works with any Ruby implementation.

h2. Installation

Typhoeus requires you to have a current version of libcurl installed. I've tested this with 7.19.4 and higher.
Typhoeus requires you to have a current version of libcurl installed. The easiest solution is to use your system's package manager to install it. If that doesn't work, you can grab a package off of "the curl website":http://curl.haxx.se/download.html and manually install it following the instructions given there. Typhoeus will work with version 7.19.4 or higher (earlier versions might work but no guarantees are provided).

To install Typhoeus, simply run:
<pre>
gem install typhoeus
</pre>
</pre>
If you're on Debian or Ubuntu and getting errors while trying to install, it could be because you don't have the latest version of libcurl installed. Do this to fix:
<pre>
sudo apt-get install libcurl4-gnutls-dev
</pre>
There's also something built in so that if you have a super old version of curl that you can't get rid of for some reason, you can install in a user directory and specify that during installation like so:
<pre>
gem install typhoeus --source http://gemcutter.org -- --with-curl=/usr/local/curl/7.19.7/
</pre>

-Another problem could be if you are running Mac Ports and you have libcurl installed through there. You need to uninstall it for Typhoeus to work! The version in Mac Ports is old and doesn't play nice. You should "download curl":http://curl.haxx.se/download.html and build from source. Then you'll have to install the gem again.- The current version of Mac Ports (7.21.2) works just fine.

If you're still having issues, please let me know on "the mailing list":http://groups.google.com/group/typhoeus.

There's one other thing you should know. The Easy object (which is just a libcurl thing) allows you to set timeout values in milliseconds. However, for this to work you need to build libcurl with c-ares support built in.

h2. Windows Support

Typhoeus runs perfectly on Windows. The tricky part is knowing how to install libcurl in the absence of a package manager.

To install libcurl, simply grab "the latest libcurl package":http://curl.haxx.se/download.html#Win32 off of the curl website, extract the bin directory, and then add the path to the bin directory into the PATH environment variable. Ruby with then be able to find libcurl properly and everything will just work.

h2. Usage

*Deprecation Warning!*
Expand Down Expand Up @@ -372,11 +371,9 @@ We can see from this that NET::HTTP performs as expected, taking 10 seconds to r

h2. Running the specs

Running the specs requires the native extensions to be built and a couple of Sinatra servers to be booted. Do this:
Running the specs requires a couple of Sinatra servers to be booted. rake spec will do this for you, but if you're needing to run the specs a lot, spinning up the servers manually and leaving them running should speed things up a bit. Do this:

<pre>
# Make sure to build the native extensions
rake build_native
# Start up the test servers (in another terminal)
rake start_test_servers

Expand Down
22 changes: 7 additions & 15 deletions Rakefile
Original file line number Diff line number Diff line change
Expand Up @@ -5,30 +5,21 @@ RSpec::Core::RakeTask.new do |t|
end

task :install do
$:.unshift File.expand_path('../lib', __FILE__)
require 'typhoeus/version'

rm_rf "*.gem"
puts `gem build typhoeus.gemspec`
puts `gem install typhoeus-#{Typhoeus::VERSION}.gem`
end

desc "Builds the native code"
task :build_native do
system("cd ext/typhoeus && ruby extconf.rb && make clean && make")
puts `gem install typhoeus-*.gem`
end

desc "Start up the test servers"
task :start_test_servers do
require 'rbconfig'
require File.expand_path('../spec/support/spawn', __FILE__)

puts "Starting 3 test servers"

pids = []
[3000, 3001, 3002].each do |port|
if pid = fork
pids << pid
else
exec('ruby', 'spec/servers/app.rb', '-p', port.to_s)
end
pids << spawn(RbConfig::CONFIG['ruby_install_name'], 'spec/servers/app.rb', '-p', port.to_s)
end

at_exit do
Expand All @@ -39,8 +30,9 @@ task :start_test_servers do
end

# Wait for kill.
trap("TERM") { exit } # for jruby to handle kill properly
sleep
end

desc "Build Typhoeus and run all the tests."
task :default => [:build_native, :spec]
task :default => [:spec]
2 changes: 1 addition & 1 deletion lib/typhoeus.rb
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@
require 'digest/sha2'
require 'typhoeus/utils'
require 'typhoeus/normalized_header_hash'
require 'typhoeus/curl'
require 'typhoeus/easy'
require 'typhoeus/form'
require 'typhoeus/multi'
require 'typhoeus/native'
require 'typhoeus/filter'
require 'typhoeus/remote_method'
require 'typhoeus/remote'
Expand Down