libc-eventmachine 0.12.5.42

data/Rakefile

@@ -0,0 +1,195 @@
+#!/usr/bin/env rake
+#--
+# Ruby/EventMachine
+#   http://rubyeventmachine.com
+#   Copyright (C) 2006-07 by Francis Cianfrocca
+#
+#   This program is copyrighted free software. You may use it under
+#   the terms of either the GPL or Ruby's License. See the file
+#   COPYING in the EventMachine distribution for full licensing
+#   information.
+#
+# $Id$
+#++
+
+### OLD RAKE: ###
+# # The tasks and external gemspecs we used to generate binary gems are now
+# # obsolete. Use Patrick Hurley's gembuilder to build binary gems for any
+# # desired platform.
+# # To build a binary gem on Win32, ensure that the include and lib paths
+# # both contain the proper references to OPENSSL. Use the static version
+# # of the libraries, not the dynamic, otherwise we expose the user to a
+# # runtime dependency.
+# 
+# # To build a binary gem for win32, first build rubyeventmachine.so
+# # using VC6 outside of the build tree (the normal way: ruby extconf.rb,
+# # and then nmake). Then copy rubyeventmachine.so into the lib directory,
+# # and run rake gemwin32.
+#
+
+require 'rubygems'  unless defined?(Gem)
+require 'rake'      unless defined?(Rake)
+require 'rake/gempackagetask'
+
+Package = false # Build zips and tarballs?
+Dir.glob('tasks/*.rake').each { |r| Rake.application.add_import r }
+
+# e.g. rake EVENTMACHINE_LIBRARY=java for forcing java build tasks as defaults!
+$eventmachine_library = :java if RUBY_PLATFORM =~ /java/ || ENV['EVENTMACHINE_LIBRARY'] == 'java'
+$eventmachine_library = :pure_ruby if ENV['EVENTMACHINE_LIBRARY'] == 'pure_ruby'
+
+MAKE = ENV['MAKE'] || if RUBY_PLATFORM =~ /mswin/ # mingw uses make.
+  'nmake'
+else
+  'make'
+end
+
+# If running under rubygems...
+__DIR__ ||= File.expand_path(File.dirname(__FILE__))
+if Gem.path.map{|path| Dir.chdir(path){ Dir.pwd } rescue path }.any? {|path| %r(^#{Regexp.escape path}) =~ __DIR__}
+  task :default => :gem_build
+else
+  desc "Build gemspec, then build eventmachine, then run tests."
+  task :default => [:build, :test]
+end
+
+desc ":default build when running under rubygems."
+task :gem_build => :build
+
+desc "Build extension (or EVENTMACHINE_LIBRARY) and place in lib"
+build_task = 'ext:build'
+build_task = 'java:build' if $eventmachine_library == :java
+build_task = :dummy_build if $eventmachine_library == :pure_ruby
+task :build => build_task do |t|
+  Dir.glob('{ext,java/src,ext/fastfilereader}/*.{so,bundle,dll,jar}').each do |f|
+    mv f, "lib"
+  end
+end
+
+task :dummy_build
+
+# Basic clean definition, this is enhanced by imports aswell.
+task :clean do
+  chdir 'ext' do
+    sh "#{MAKE} clean" if test ?e, 'Makefile'
+  end
+  chdir 'ext/fastfilereader' do
+    sh "#{MAKE} clean" if test ?e, 'Makefile'
+  end
+  Dir.glob('**/Makefile').each { |file| rm file }
+  Dir.glob('**/*.{o,so,bundle,class,jar,dll,log}').each { |file| rm file }
+  Dir.glob('ext/**/conftest.dSYM').each{ |file| rm_rf file }
+end
+
+Spec = Gem::Specification.new do |s|
+  s.name              = "eventmachine"
+  s.summary           = "Ruby/EventMachine library"
+  s.platform          = Gem::Platform::RUBY
+
+  s.has_rdoc          = true
+  s.rdoc_options      = %w(--title EventMachine --main docs/README --line-numbers)
+  s.extra_rdoc_files  = Dir['docs/*']
+
+  s.files             = %w(Rakefile) + Dir["{bin,tests,lib,ext,java,tasks}/**/*"]
+
+  s.require_path      = 'lib'
+
+  # TODO / XXX - should we enable this? rubygems fails the install if anything 
+  # is broken. What we could do is CI submission, though, and always terminate
+  # with a positive code...
+  # s.test_file         = "tests/testem.rb"
+
+  # XXX Using rake to compile extensions breaks when you have multiple ruby installations
+  # and your path isn't set. We can switch back to this once the Gem.exec patch is merged.
+  # s.extensions        = "Rakefile"
+  s.extensions        = ["ext/extconf.rb", "ext/fastfilereader/extconf.rb"]
+
+  s.author            = "Francis Cianfrocca"
+  s.email             = "garbagecat10@gmail.com"
+  s.rubyforge_project = 'eventmachine'
+  s.homepage          = "http://rubyeventmachine.com"
+
+  # Pulled in from readme, as code to pull from readme was not working!
+  # Might be worth removing as no one seems to use gem info anyway.
+  s.description = <<-EOD
+EventMachine implements a fast, single-threaded engine for arbitrary network
+communications. It's extremely easy to use in Ruby. EventMachine wraps all
+interactions with IP sockets, allowing programs to concentrate on the
+implementation of network protocols. It can be used to create both network
+servers and clients. To create a server or client, a Ruby program only needs
+to specify the IP address and port, and provide a Module that implements the
+communications protocol. Implementations of several standard network protocols
+are provided with the package, primarily to serve as examples. The real goal
+of EventMachine is to enable programs to easily interface with other programs
+using TCP/IP, especially if custom protocols are required.
+  EOD
+
+  require 'lib/eventmachine_version'
+  s.version = EventMachine::VERSION
+end
+
+namespace :ext do
+  ext_sources = FileList['ext/*.{h,cpp,rb,c}']
+  ffr_sources = FileList['ext/fastfilereader/*.{h,cpp,rb}']
+  
+  desc "Build C++ extension"
+  task :build => [:make]
+  
+  desc "make extensions"
+  task :make => ext_sources + ['ext/Makefile'] do
+    chdir 'ext' do
+      sh MAKE
+    end
+  end
+  task :make => ffr_sources + ['ext/fastfilereader/Makefile'] do
+    chdir 'ext/fastfilereader' do
+      sh MAKE
+    end
+  end
+  
+  desc 'Compile the makefile'
+  file 'ext/Makefile' => ext_sources do
+    chdir 'ext' do
+      ruby 'extconf.rb'
+    end
+  end
+
+  desc 'Compile fastfilereader makefile'
+  file 'ext/fastfilereader/Makefile' => ffr_sources do
+    chdir 'ext/fastfilereader' do
+      ruby 'extconf.rb'
+    end
+  end
+end
+  
+namespace :java do
+  # This task creates the JRuby JAR file and leaves it in the lib directory.
+  # This step is required before executing the jgem task.
+  desc "Build java extension"
+  task :build => [:jar] do |t|
+    chdir('java/src') do
+      mv 'em_reactor.jar', '../../lib/em_reactor.jar'
+    end
+  end
+  
+  desc "compile .java to .class"
+  task :compile do
+    chdir('java/src') do
+      sh 'javac com/rubyeventmachine/*.java'
+    end
+  end
+  
+  desc "compile .classes to .jar"
+  task :jar => [:compile] do
+    chdir('java/src') do
+      sh "jar -cf em_reactor.jar com/rubyeventmachine/*.class"
+    end
+  end
+end
+
+task :gemspec => :clobber do
+  open("eventmachine.gemspec", 'w') { |f| f.write Spec.to_ruby }
+end
+
+task :clobber => :clean
+task :test => :build

data/docs/COPYING

@@ -0,0 +1,60 @@
+EventMachine is copyrighted free software owned by Francis Cianfrocca
+(blackhedd ... gmail.com). The Owner of this software permits you to
+redistribute and/or modify the software under either the terms of the GPL
+version 2 (see the file GPL), or the conditions below ("Ruby License"):
+
+  1. You may make and give away verbatim copies of the source form of this
+     software without restriction, provided that you retain ALL of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the Owner.
+
+  3. You may distribute the software in object code or binary form,
+     provided that you do at least ONE of the following:
+
+       a) distribute the binaries and library files of the software,
+	  together with instructions (in a manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the Owner.
+
+  4. You may modify and include parts of the software into any other
+     software (possibly commercial), provided you comply with the terms in
+     Sections 1, 2, and 3 above. But some files in the distribution
+     are not written by the Owner, so they may be made available to you
+     under different terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whoever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/docs/ChangeLog

@@ -0,0 +1,211 @@
+01Oct06: Replaced EventMachine#open_datagram_server with a version that can
+  take a Class or a Module, instead of just a Module. Thanks to Tobias
+  Gustafsson for pointing out the missing case.
+04Oct06: Supported subsecond timer resolutions, per request by Jason Roelofs.
+05Oct06: Added EventMachine#set_quantum, which sets the timer resolution.
+15Nov06: Added Connection#set_comm_inactivity_timeout.
+15Nov06: Checked in a Line-and-Text Protocol Handler.
+18Nov06: Checked in a Header-and-Body Protocol Handler.
+22Nov06: Changed EventMachine#reconnect: no longer excepts when called on an
+         already-connected handler.
+28Nov06: Supported a binary-unix gem.
+19Dec06: Added EventMachine#set_effective_user.
+05Jan07: Upped max outstanding timers to 1000.
+15May07: Applied Solaris patches from Brett Eisenberg
+22May07: Cleaned up the license text in all the source files.
+22May07: Released version 0.7.2
+
+23May07: Per suggestion from Bill Kelly, fixed a bug with the initialization
+ 	of the network libraries under Windows. The goal is to enable EM to
+	be used without Ruby.
+28May07: Applied patch from Bill Kelly, refactors the declarations of
+	event names to make EM easier to use from C programs without Ruby.
+31May07: Added a preliminary implementation of EventMachine#popen.
+01Jun07: Added EM, a "pseudo-alias" for EventMachine.
+01Jun07: Added EM#next_tick.
+01Jun07: Added EM::Connection#get_outbound_data_size
+05Jun07: Removed the code which loads a pure-Ruby EM library in case the
+	compiled extension is unavailable. Suggested by Moshe Litvin.
+06Jun07: Preliminary epoll implementation.
+12Jun07: Added an evented popen implementation that, like Ruby's, is
+	full-duplex and makes the subprocess PID available to the caller.
+06Jul07: Performance-tweaked the callback dispatcher in eventmachine.rb.
+10Jul07: Released version 0.8.0.
+12Jul07: Applied patches from Tim Pease to fix Solaris build problems.
+15Jul07: Created a new provisional source branch, experiments/jruby-1.
+	This is a preliminary implementation of the EM reactor in Java,
+	suitable for use with JRuby.
+17Jul07: Added EventMachine#stop_server, per request from Kirk Haines,
+	and associated unit tests.
+22Jul07: Added EventMachine#stream_file_data. This is a very fast and scalable
+	way of sending data from static files over network connections. It
+	has separate implementations for small files and large file, and
+	has tunings to minimize memory consumption.
+26Jul07: Added some patches by Kirk Haines to improve the behavior of
+	EM::Connection#send_file_data_to_connection.
+26Jul07: Added a C++ module for directly integrating EM into C++ programs
+	with no Ruby dependencies. Needs example code.
+29Jul07: Added EventMachine::Protocols::LineText2.
+29Jul07: Added EventMachine::Protocols::Stomp.
+30Jul07: Added sys/stat.h to project.h to fix compilation bug on Darwin.
+13Aug07: Added EventMachine#reactor_running?
+15Aug07: Added parameters for EventMachine::Connection:start_tls that can be
+	used to specify client-side private keys and certificates.
+17Aug07: Added EventMachine#run_block, a sugaring for a common use case.
+24Aug07: Added a preliminary keyboard handler. Needs docs and testing on
+	windows.
+26Aug07: Created EventMachine::Spawnable, an implementation of Erlang-like
+	processes.
+27Aug07: Silenced some -w warnings, requested by James Edward Gray II.
+30Aug07: Added cookies to EM::HttpClient#request.
+04Sep07: Added an initial implementation of an evented SMTP client.
+04Sep07: Added an initial implementation of an evented SMTP server.
+10Sep07: Changed EM#spawn to run spawned blocks in the context of the
+	SpawnedProcess object, not of whatever was the active object at the
+	time of the spawn.
+14Sep07: Heartbeats weren't working with EPOLL. Noticed by Brian Candler.
+15Sep07: Added some features, tests and documents to Deferrable.
+16Sep07: Added [:content] parameter to EM::Protocols::SmtpClient#send.
+16Sep07: Bumped version to 0.9.0 in anticipation of a release.
+18Sep07: Released version 0.9.0.
+19Sep07: Added #receive_reset to EM::Protocols::SmtpServer.
+19Sep07: User overrides of EM::Protocols::SmtpServer#receive_recipient can now
+	return a Deferrable. Also fixed bug: SmtpClient now raises a protocol
+	error if none of its RCPT TO: commands are accepted by the server.
+26Sep07: Fixed missing keyboard support for Windows.
+03Oct07: Added a default handler for RuntimeErrors emitted from user-written
+	code. Suggested by Brian Candler.
+19Oct07: Set the SO_BROADCAST option automatically on all UDP sockets.
+10Nov07: Forced integer conversion of send_datagram's port parameter.
+Suggested by Matthieu Riou.
+12Nov07: Added saslauth.rb, a protocol module to replace the Cyrus SASL
+daemons saslauthd and pwcheck.
+15Nov07: Fixed bug reported by Mark Zvillius. We were failing to dispatch
+	zero-length datagrams under certain conditions.
+19Nov07: Added EventMachine#set_max_timers. Requested by Matthieu Riou and
+	others.
+19Nov07: Fixed bug with EM::Connection#start_tls. Was not working with server
+	connections. Reported by Michael S. Fischer.
+26Nov07: Supported a hack for EventMachine#popen so it can return an exit
+	status from subprocesses. Requested by Michael S. Fischer.
+30Nov07: Changed Pipe descriptors so that the child-side of the socketpair is
+	NOT set nonblocking. Suggested by Duane Johnson.
+05Dec07: Re-enabled the pure-Ruby implementation.
+06Dec07: Released Version 0.10.0.
+13Dec07: Added EM::DeferrableChildProcess
+24Dec07: Added a SASL client for simple password authentication.
+27Dec07: Removed the hookable error handler. No one was using it and it significantly
+	degraded performance.
+30Dec07: Implemented Kqueue support for OSX and BSD.
+04Jan08: Fixed bug in epoll ("Bad file descriptor"), patch supplied by Chris
+	Heath.
+04Jan08: Fixed bug reported by Michael S. Fischer. We were terminating
+	SSL connections that sent data before the handshake was complete.
+08Jan08: Added an OpenBSD branch for extconf.rb, contributed by Guillaume
+	Sellier.
+19Jan08: Added EM::Connection::get_sockname per request by Michael Fischer.
+19Jan08: Supported IPv6 addresses.
+30Apr08: Set the NODELAY option on sockets that we connect to other servers.
+	Omission noted by Roger Pack.
+14May08: Generated a 0.12 release.
+15May08: Supported EM#get_sockname for acceptors (TCP server sockets).
+	Requested by Roger Pack.
+15May08; Accepted a patch from Dan Aquino that allows the interval of a
+	PeriodicTimer to be changed on the fly.
+15Jun08: Supported nested calls to EM#run. Many people contributed ideas to
+	this, notably raggi and tmm1.
+20Jul08: Accepted patch from tmm1 for EM#fork_reactor.
+28Jul08: Added a Postgres3 implementation, written by FCianfrocca.
+14Aug08: Added a patch by Mike Murphy to support basic auth in the http
+client.
+28Aug08: Added a patch by tmm1 to fix a longstanding problem with Java
+data-sends.
+13Sep08: Added LineText2#set_binary_mode, a back-compatibility alias.
+13Sep08: Modified the load order of protocol libraries in eventmachine.rb
+	to permit a modification of HeaderAndContentProtocol.
+13Sep08: Modified HeaderAndContent to use LineText2, which is less buggy
+	than LineAndTextProtocol. This change may be reversed if we can fix
+	the bugs in buftok.
+13Sep08: Improved the password handling in the Postgres protocol handler.
+15Sep08: Added attach/detach, contributed by Aman Gupta (tmm1) and Riham Aldakkak,
+	to support working with file descriptors not created in the reactor.
+16Sep08: Added an optional version string to the HTTP client. This is a hack
+	that allows a client to specify a version 1.0 request, which
+	keeps the server from sending a chunked response. The right way to
+	solve this, of course, is to support chunked responses.
+23Sep08: ChangeLog Summary for Merge of branches/raggi
+Most notable work and patches by Aman Gupta, Roger Pack, and James Tucker. 
+Patches / Tickets also submitted by: Jeremy Evans, aanand, darix, mmmurf, 
+danielaquino, macournoyer.
+ - Moved docs into docs/ dir
+ - Major refactor of rakefile, added generic rakefile helpers in tasks
+ - Added example CPP build rakefile in tasks/cpp.rake
+ - Moved rake tests out to tasks/tests.rake
+ - Added svn ignores where appropriate
+ - Fixed jruby build on older java platforms
+ - Gem now builds from Rakefile rather than directly via extconf
+ - Gem unified for jruby, C++ and pure ruby.
+ - Correction for pure C++ build, removing ruby dependency
+ - Fix for CYGWIN builds on ipv6
+ - Major refactor for extconf.rb
+ - Working mingw builds
+ - extconf optionally uses pkg_config over manual configuration
+ - extconf builds for 1.9 on any system that has 1.9
+ - extconf no longer links pthread explicitly
+ - looks for kqueue on all *nix systems
+ - better error output on std::runtime_error, now says where it came from
+ - Fixed some tests on jruby
+ - Added test for general send_data flaw, required for a bugfix in jruby build
+ - Added timeout to epoll tests
+ - Added fixes for java reactor ruby api
+ - Small addition of some docs in httpclient.rb and httpcli2.rb
+ - Some refactor and fixes in smtpserver.rb
+ - Added parenthesis where possible to avoid excess ruby warnings
+ - Refactor of $eventmachine_library logic for accuracy and maintenance, jruby
+ - EM::start_server now supports unix sockets
+ - EM::connect now supports unix sockets
+ - EM::defer @threadqueue now handled more gracefully
+ - Added better messages on exceptions raised
+ - Fix edge case in timer fires
+ - Explicitly require buftok.rb
+ - Add protocols to autoload, rather than require them all immediately
+ - Fix a bug in pr_eventmachine for outbound_q
+ - Refactors to take some of the use of defer out of tests.
+ - Fixes in EM.defer under start/stop conditions. Reduced scope of threads.
+23Sep08: Added patch from tmm1 to avoid popen errors on exit.
+30Sep08: Added File.exists? checks in the args for start_tls, as suggested by
+  Brian Lopez (brianmario).
+10Nov08: ruby 1.9 compatibility enhancements
+28Nov08: Allow for older ruby builds where RARRAY_LEN is not defined
+03Dec08: allow passing arguments to popen handlers
+13Jan09: SSL support for httpclient2 (David Smalley)
+22Jan09: Fixed errors on OSX with the kqueue reactor, fixed errors in the pure
+  ruby reactor. Added EM.current_time. Added EM.epoll? and EM.kqueue?
+27Jan09: Reactor errors are now raised as ruby RuntimeErrors.
+28Jan09: Documentation patch from alloy
+29Jan09: (Late sign-off) Use a longer timeout for connect_server (Ilya
+  Grigorik)
+07Feb09: Fix signal handling issues with threads+epoll
+07Feb09: Use rb_thread_schedule in the epoll reactor
+07Feb09: Use TRAP_BEG/END and rb_thread_schedule in kqueue reactor
+08Feb09: Added fastfilereader from swiftiply
+08Feb09: 1.9 fix for rb_trap_immediate
+08Feb09: Enable rb_thread_blocking_region for 1.9.0 and 1.9.1
+10Feb09: Support win32 builds for fastfilereader
+10Feb09: Added a new event to indicate completion of SSL handshake on TCP
+  connections
+10Feb09: Working get_peer_cert method. Returns the certificate as a Ruby
+  String in PEM format. (Jake Douglas)
+10Feb09: Added EM.get_max_timers
+11Feb09: Fix compile options for sun compiler (Alasdairrr)
+11Feb09: get_status returns a Process::Status object
+12Feb09: Add EM::Protocols::Memcache with simple get/set functionality
+19Feb09: Add catch-all EM.error_handler
+20Feb09: Support miniunit (1.9)
+20Feb09: Return success on content-length = 0 instead of start waiting forever
+  (Ugo Riboni)
+25Feb09: Allow next_tick to be used to pre-schedule reactor operations before
+  EM.run
+26Feb09: Added EM.get_connection_count
+01Mar09: Switch back to extconf for compiling gem extensions
+01Mar09: fixed a small bug with basic auth (mmmurf)

data/docs/DEFERRABLES

@@ -0,0 +1,138 @@
+$Id$
+
+[DOCUMENT UNDER CONSTRUCTION]
+
+EventMachine (EM) adds two different formalisms for lightweight concurrency to the Ruby programmer's toolbox: spawned processes and deferrables. This note will show you how to use deferrables. For more information, see the separate document LIGHTWEIGHT_CONCURRENCY.
+
+
+=== What are Deferrables?
+
+EventMachine's Deferrable borrows heavily from the "deferred" object in Python's "Twisted" event-handling framework. Here's a minimal example that illustrates Deferrable:
+
+ require 'eventmachine'
+ 
+ class MyClass
+   include EM::Deferrable
+ 
+   def print_value x
+     puts "MyClass instance received #{x}"
+   end
+ end
+ 
+ EM.run {
+   df = MyClass.new
+   df.callback {|x|
+     df.print_value(x)
+     EM.stop
+   }
+ 
+   EM::Timer.new(2) {
+     df.set_deferred_status :succeeded, 100
+   }
+ }
+ 
+
+This program will spin for two seconds, print out the string "MyClass instance received 100" and then exit. The Deferrable pattern relies on an unusual metaphor that may be unfamiliar to you, unless you've used Python's Twisted. You may need to read the following material through more than once before you get the idea.
+
+EventMachine::Deferrable is simply a Ruby Module that you can include in your own classes. (There also is a class named EventMachine::DefaultDeferrable for when you want to create one without including it in code of your own.)
+
+An object that includes EventMachine::Deferrable is like any other Ruby object: it can be created whenever you want, returned from your functions, or passed as an argument to other functions.
+
+The Deferrable pattern allows you to specify any number of Ruby code blocks (callbacks or errbacks) that will be executed at some future time when the status of the Deferrable object changes.
+
+How might that be useful? Well, imagine that you're implementing an HTTP server, but you need to make a call to some other server in order to fulfill a client request.
+
+When you receive a request from one of your clients, you can create and return a Deferrable object. Some other section of your program can add a callback to the Deferrable that will cause the client's request to be fulfilled. Simultaneously, you initiate an event-driven or threaded client request to some different server. And then your EM program will continue to process other events and service other client requests.
+
+When your client request to the other server completes some time later, you will call the #set_deferred_status method on the Deferrable object, passing either a success or failure status, and an arbitrary number of parameters (which might include the data you received from the other server).
+
+At that point, the status of the Deferrable object becomes known, and its callback or errback methods are immediately executed. Callbacks and errbacks are code blocks that are attached to Deferrable objects at any time through the methods #callback and #errback.
+
+The deep beauty of this pattern is that it decouples the disposition of one operation (such as a client request to an outboard server) from the subsequent operations that depend on that disposition (which may include responding to a different client or any other operation).
+
+The code which invokes the deferred operation (that will eventually result in a success or failure status together with associated data) is completely separate from the code which depends on that status and data. This achieves one of the primary goals for which threading is typically used in sophisticated applications, with none of the nondeterminacy or debugging difficulties of threads.
+
+As soon as the deferred status of a Deferrable becomes known by way of a call to #set_deferred_status, the Deferrable will IMMEDIATELY execute all of its callbacks or errbacks in the order in which they were added to the Deferrable.
+
+Callbacks and errbacks can be added to a Deferrable object at any time, not just when the object is created. They can even be added after the status of the object has been determined! (In this case, they will be executed immediately when they are added.)
+
+A call to Deferrable#set_deferred_status takes :succeeded or :failed as its first argument. (This determines whether the object will call its callbacks or its errbacks.) #set_deferred_status also takes zero or more additional parameters, that will in turn be passed as parameters to the callbacks or errbacks.
+
+In general, you can only call #set_deferred_status ONCE on a Deferrable object. A call to #set_deferred_status will not return until all of the associated callbacks or errbacks have been called. If you add callbacks or errbacks AFTER making a call to #set_deferred_status, those additional callbacks or errbacks will execute IMMEDIATELY. Any given callback or errback will be executed AT MOST once.
+
+It's possible to call #set_deferred_status AGAIN, during the execution a callback or errback. This makes it possible to change the parameters which will be sent to the callbacks or errbacks farther down the chain, enabling some extremely elegant use-cases. You can transform the data returned from a deferred operation in arbitrary ways as needed by subsequent users, without changing any of the code that generated the original data.
+
+A call to #set_deferred_status will not return until all of the associated callbacks or errbacks have been called. If you add callbacks or errbacks AFTER making a call to #set_deferred_status, those additional callbacks or errbacks will execute IMMEDIATELY.
+
+Let's look at some more sample code. It turns out that many of the internal protocol implementations in the EventMachine package rely on Deferrable. One of these is EM::Protocols::HttpClient.
+
+To make an evented HTTP request, use the module function EM::Protocols::HttpClient#request, which returns a Deferrable object. Here's how:
+
+ require 'eventmachine'
+ 
+ EM.run {
+   df = EM::Protocols::HttpClient.request( :host=>"www.example.com", :request=>"/index.html" )
+ 
+   df.callback {|response|
+     puts "Succeeded: #{response[:content]}"
+     EM.stop
+   }
+ 
+   df.errback {|response|
+     puts "ERROR: #{response[:status]}"
+     EM.stop
+   }
+ }
+
+(See the documentation of EventMachine::Protocols::HttpClient for information on the object returned by #request.)
+
+In this code, we make a call to HttpClient#request, which immediately returns a Deferrable object. In the background, an HTTP client request is being made to www.example.com, although your code will continue to run concurrently.
+
+At some future point, the HTTP client request will complete, and the code in EM::Protocols::HttpClient will process either a valid HTTP response (including returned content), or an error.
+
+At that point, EM::Protocols::HttpClient will call EM::Deferrable#set_deferred_status on the Deferrable object that was returned to your program, as the return value from EM::Protocols::HttpClient.request. You don't have to do anything to make this happen. All you have to do is tell the Deferrable what to do in case of either success, failure, or both.
+
+In our code sample, we set one callback and one errback. The former will be called if the HTTP call succeeds, and the latter if it fails. (For simplicity, we have both of them calling EM#stop to end the program, although real programs would be very unlikely to do this.)
+
+Setting callbacks and errbacks is optional. They are handlers to defined events in the lifecycle of the Deferrable event. It's not an error if you fail to set either a callback, an errback, or both. But of course your program will then fail to receive those notifications.
+
+If through some bug it turns out that #set_deferred_status is never called on a Deferrable object, then that object's callbacks or errbacks will NEVER be called. It's also possible to set a timeout on a Deferrable. If the timeout elapses before any other call to #set_deferred_status, the Deferrable object will behave as is you had called set_deferred_status(:failed) on it.
+
+
+Now let's modify the example to illustrate some additional points:
+
+ require 'eventmachine'
+ 
+ EM.run {
+   df = EM::Protocols::HttpClient.request( :host=>"www.example.com", :request=>"/index.html" )
+ 
+   df.callback {|response|
+     df.set_deferred_status :succeeded, response[:content]
+   }
+ 
+   df.callback {|string|
+     puts "Succeeded: #{string}"
+     EM.stop
+   }
+ 
+   df.errback {|response|
+     puts "ERROR: #{response[:status]}"
+     EM.stop
+   }
+ }
+
+
+Just for the sake of illustration, we've now set two callbacks instead of one. If the deferrable operation (the HTTP client-request) succeeds, then both of the callbacks will be executed in order.
+
+But notice that we've also made our own call to #set_deferred_status in the first callback. This isn't required, because the HttpClient implementation already made a call to #set_deferred_status. (Otherwise, of course, the callback would not be executing.)
+
+But we used #set_deferred_status in the first callback in order to change the parameters that will be sent to subsequent callbacks in the chain. In this way, you can construct powerful sequences of layered functionality. If you want, you can even change the status of the Deferrable from :succeeded to :failed, which would abort the chain of callback calls, and invoke the chain of errbacks instead.
+
+Now of course it's somewhat trivial to define two callbacks in the same method, even with the parameter-changing effect we just described. It would be much more interesting to pass the Deferrable to some other function (for example, a function defined in another module or a different gem), that would in turn add callbacks and/or errbacks of its own. That would illustrate the true power of the Deferrable pattern: to isolate the HTTP client-request from other functions that use the data that it returns without caring where those data came from.
+
+Remember that you can add a callback or an errback to a Deferrable at any point in time, regardless of whether the status of the deferred operation is known (more precisely, regardless of when #set_deferred_status is called on the object). Even hours or days later.
+
+When you add a callback or errback to a Deferrable object on which #set_deferred_status has not yet been called, the callback/errback is queued up for future execution, inside the Deferrable object. When you add a callback or errback to a Deferrable on which #set_deferred_status has already been called, the callback/errback will be executed immediately. Your code doesn't have to worry about the ordering, and there are no timing issues, as there would be with a threaded approach.
+
+For more information on Deferrables and their typical usage patterns, look in the EM unit tests. There are also quite a few sugarings (including EM::Deferrable#future) that make typical Deferrable usages syntactically easier to work with.
+