rainbows 0.6.0 → 0.7.0

data/.document

@@ -10,3 +10,4 @@ SIGNALS
 TODO
 TUNING
 vs_Unicorn
+Summary

data/Documentation/GNUmakefile

@@ -26,5 +26,8 @@ install-man: man
 %.1.html: %.1.txt
 	$(pandoc_html) < $< > $@+ && mv $@+ $@
 
+comparison.html: comparison.haml
+	haml -t ugly < $< > $@+ && mv $@+ $@
+
 clean::
-	$(RM) $(man1) $(html1)
+	$(RM) $(man1) $(html1) comparison.html

data/Documentation/comparison.css

@@ -0,0 +1,6 @@
+/* help to make this look nice would be greatly appreciated */
+.comparison {
+	margin: 1em;
+	border: 1px solid;
+	width: 100%;
+}

data/Documentation/comparison.haml

@@ -0,0 +1,297 @@
+%h2 core features and compatibility
+%br
+%table.comp
+  %tr.comp_header
+    %th.mod module
+    %th.tee rack.input streaming
+    %th.r18 Ruby 1.8
+    %th.r19 Ruby 1.9
+    %th.rbx Rubinius
+    %th.slow slow clients
+  %tr.comp_base
+    %td.mod Unicorn/Base
+    %td.tee Yes
+    %td.r18 Yes
+    %td.r19 Yes
+    %td.rbx Yes
+    %td.slow No
+  %tr.comp_row
+    %td.mod Revactor
+    %td.tee Yes
+    %td.r18 No
+    %td.r19 Yes
+    %td.rbx No
+    %td.slow Yes
+  %tr.comp_row
+    %td.mod ThreadPool
+    %td.tee Yes
+    %td.r18 Yes
+    %td.r19 Yes
+    %td.rbx Yes
+    %td.slow OK
+  %tr.comp_row
+    %td.mod Rev
+    %td.tee No
+    %td.r18 Yes
+    %td.r19 Yes
+    %td.rbx No
+    %td.slow Yes
+  %tr.comp_row
+    %td.mod ThreadSpawn
+    %td.tee Yes
+    %td.r18 Yes
+    %td.r19 Yes
+    %td.rbx Yes
+    %td.slow OK
+  %tr.comp_row
+    %td.mod EventMachine
+    %td.tee No
+    %td.r18 Yes
+    %td.r19 Yes
+    %td.rbx No
+    %td.slow Yes
+  %tr.comp_row
+    %td.mod RevThreadSpawn
+    %td.tee No
+    %td.r18 Slow*
+    %td.r19 Yes
+    %td.rbx No
+    %td.slow Yes
+  %tr.comp_row
+    %td.mod FiberSpawn
+    %td.tee Yes
+    %td.r18 No
+    %td.r19 Yes
+    %td.rbx No
+    %td.slow Yes
+  %tr.comp_row
+    %td.mod FiberPool
+    %td.tee Yes
+    %td.r18 No
+    %td.r19 Yes
+    %td.rbx No
+    %td.slow Yes
+  %tr.comp_base
+    %td.mod ActorSpawn
+    %td.tee Yes
+    %td.r18 Not yet
+    %td.r19 No
+    %td.rbx Yes
+    %td.slow Yes
+  %tr.comp_base
+    %td.mod NeverBlock
+    %td.tee No
+    %td.r18 Yes
+    %td.r19 Yes
+    %td.rbx No
+    %td.slow Yes
+%ul
+  %li
+    RevThreadSpawn + 1.8 performance is being improved, follow
+    the
+    %a(href="http://rubyforge.org/mailman/listinfo/rev-talk")
+      rev-talk mailing list
+    for details.
+  %li
+    waiting on Rubinius for better signal handling
+  %li
+    rack.input streaming is what makes
+    %a(href="http://upr.bogomips.org/") upload progress,
+    BOSH, and Web Sockets possible
+  %li
+    rack.input streaming is NOT compatible with current versions of nginx
+    or any proxy that fully buffers request bodies before proxying.
+    Keep in mind request body buffering in nginx is a good thing in all
+    other cases where rack.input streaming is not needed.
+
+%h2 application requirements
+%br
+%table.comp
+  %tr.comp_header
+    %th.mod module
+    %th.slowio slow I/O (backend, not client)
+    %th.thr thread safety
+    %th.reent single thread reentrant
+  %tr.comp_base
+    %td.mod Unicorn/Base
+    %td.slowio avoid
+    %td.thr No
+    %td.reent No
+  %tr.comp_row
+    %td.mod Revactor
+    %td.slowio
+      %a(href="http://rev.rubyforge.org/")Rev,
+      %a(href="http://revactor.org/")Revactor,
+      %b
+        not
+      %a(href="Rainbows/Fiber/IO.html")Fiber::IO
+    %td.thr No
+    %td.reent Yes
+  %tr.comp_row
+    %td.mod ThreadPool
+    %td.slowio thread-safe Ruby
+    %td.thr Yes
+    %td.reent No
+  %tr.comp_row
+    %td.mod Rev
+    %td.slowio
+      %a(href="http://rev.rubyforge.org/") Rev
+    %td.thr No
+    %td.reent No
+  %tr.comp_row
+    %td.mod ThreadSpawn
+    %td.slowio thread-safe Ruby
+    %td.thr Yes
+    %td.reent No
+  %tr.comp_row
+    %td.mod EventMachine
+    %td.slowio
+      %a(href="http://rubyeventmachine.com") EventMachine
+    %td.thr No
+    %td.reent No
+  %tr.comp_row
+    %td.mod RevThreadSpawn
+    %td.slowio
+      thread-safe Ruby,
+      %a(href="http://rev.rubyforge.org/") Rev
+    %td.thr Yes
+    %td.reent No
+  %tr.comp_row
+    %td.mod FiberSpawn
+    %td.slowio
+      %a(href="Rainbows/Fiber/IO.html") Rainbows::Fiber::IO
+    %td.thr No
+    %td.reent Yes
+  %tr.comp_row
+    %td.mod FiberPool
+    %td.slowio
+      %a(href="Rainbows/Fiber/IO.html") Rainbows::Fiber::IO
+    %td.thr No
+    %td.reent Yes
+  %tr.comp_base
+    %td.mod ActorSpawn
+    %td.slowio thread-safe Ruby
+    %td.thr Yes
+    %td.reent Yes
+  %tr.comp_base
+    %td.mod NeverBlock
+    %td.slowio
+      %a(href="http://www.espace.com.eg/neverblock") NeverBlock,
+      %a(href="http://rubyeventmachine.com") EventMachine
+    %td.thr No
+    %td.reent Yes
+
+%ul
+  %li
+    Requirements for single thread reentrancy are loose in that there is
+    no risk of race conditions and potentially mutually exclusive to
+    thread-safety.  In the case where a Fiber yields while holding a
+    resource and another Fiber attempting to acquire it may raise
+    an error or worse, deadlock the entire process.
+  %li
+    Slow I/O means anything that can block/stall on sockets including
+    3rd-party APIs (OpenID providers included) or slow database queries.
+    Properly run Memcached (within the same LAN) is fast and not a blocker.
+    Slow I/O on POSIX filesystems only includes a few operations, namely
+    on UNIX domain sockets and named pipes.  Nearly all other operations
+    on POSIX filesystems can be considered "fast", or at least
+    uninterruptible.
+
+%h2 middlewares and frameworks
+%br
+
+%table.comp
+  %tr.comp_header
+    %th.mod model
+    %th.devfd
+      %a(href="Rainbows/DevFdResponse.html") DevFdResponse
+    %th.app_pool
+      %a(href="Rainbows/AppPool.html") AppPool
+    %th.lock
+      %a(href="http://rack.rubyforge.org/doc/Rack/Lock.html") Rack::Lock
+    %th.async async
+  %tr.comp_row
+    %td.mod Unicorn/Base
+    %td.devfd no-op
+    %td.app_pool no-op
+    %td.lock no-op
+    %td.async lots of RAM :P
+  %tr.comp_row
+    %td.mod Revactor
+    %td.devfd no-op
+    %td.app_pool Yes
+    %td.lock No!
+    %td.async Revactor itself
+  %tr.comp_row
+    %td.mod ThreadPool
+    %td.devfd no-op
+    %td.app_pool Yes
+    %td.lock Yes
+    %td.async standard Ruby
+  %tr.comp_row
+    %td.mod Rev
+    %td.devfd Yes
+    %td.app_pool no-op
+    %td.lock no-op
+    %td.async DevFdResponse
+  %tr.comp_row
+    %td.mod ThreadSpawn
+    %td.devfd no-op
+    %td.app_pool Yes
+    %td.lock Yes
+    %td.async standard Ruby
+  %tr.comp_row
+    %td.mod EventMachine
+    %td.devfd Yes
+    %td.app_pool no-op
+    %td.lock no-op
+    %td.async async_sinatra
+  %tr.comp_row
+    %td.mod RevThreadSpawn
+    %td.devfd Yes
+    %td.app_pool Yes
+    %td.lock Dumb
+    %td.async standard Ruby
+  %tr.comp_row
+    %td.mod FiberSpawn
+    %td.devfd Yes
+    %td.app_pool Yes
+    %td.lock No!
+    %td.async Rainbows::Fiber{::IO,.sleep}
+  %tr.comp_row
+    %td.mod FiberPool
+    %td.devfd Yes
+    %td.app_pool Yes
+    %td.lock No!
+    %td.async Rainbows::Fiber{::IO,.sleep}
+  %tr.comp_row
+    %td.mod ActorSpawn
+    %td.devfd no-op
+    %td.app_pool Yes
+    %td.lock Yes
+    %td.async standard Ruby
+  %tr.comp_row
+    %td.mod NeverBlock
+    %td.devfd Yes
+    %td.app_pool Yes*
+    %td.lock Yes*
+    %td.async NeverBlock, async_sinatra
+
+%ul
+  %li
+    "No!" means it's fundamentally incompatible, use an
+    %a(href="Rainbows/AppPool.html") AppPool
+    %b :size
+    of one instead.
+  %li
+    NeverBlock also supports a :pool_size option which is one less
+    layer of complexity than using AppPool.
+  %li
+    NeverBlock can neuter the Mutex class so Rack::Lock effectively
+    becomes a no-op with:
+    %br
+    %code require "never_block/frameworks/rails"
+    (before Rails is loaded)
+  %li
+    Everything that's DevFdResponse-compatible can use it for passing
+    async responses through

data/GIT-VERSION-GEN

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 GVF=GIT-VERSION-FILE
-DEF_VER=v0.6.0.GIT
+DEF_VER=v0.7.0.GIT
 
 LF='
 '

data/GNUmakefile

@@ -1,19 +1,13 @@
-# use GNU Make to run tests in parallel, and without depending on Rubygems
+# use GNU Make to run tests in parallel, and without depending on RubyGems
 all::
 RUBY = ruby
-rake = rake
+RAKE = rake
 GIT_URL = git://git.bogomips.org/rainbows.git
 
 GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
 	@./GIT-VERSION-GEN
 -include GIT-VERSION-FILE
 -include local.mk
-ifdef ruby
-  ifeq ($(RUBY),ruby)
-    $(warning ruby variable is deprecated, use RUBY instead)
-    RUBY = $(ruby)
-  endif
-endif
 ifeq ($(DLEXT),) # "so" for Linux
   DLEXT := $(shell $(RUBY) -rrbconfig -e 'puts Config::CONFIG["DLEXT"]')
 endif
@@ -61,13 +55,16 @@ manifest: $(pkg_extra) man
 	$(RM) $@+
 
 NEWS: GIT-VERSION-FILE
-	$(rake) -s news_rdoc > $@+
+	$(RAKE) -s news_rdoc > $@+
 	mv $@+ $@
 
-SINCE = 0.5.0
-ChangeLog: log_range = $(shell test -n "$(SINCE)" && echo v$(SINCE)..)
+SINCE = 0.6.0
+ChangeLog: LOG_VERSION = \
+  $(shell git rev-parse -q "$(GIT_VERSION)" >/dev/null 2>&1 && \
+          echo $(GIT_VERSION) || git describe)
+ChangeLog: log_range = v$(SINCE)..$(LOG_VERSION)
 ChangeLog: GIT-VERSION-FILE
-	@echo "ChangeLog from $(GIT_URL) ($(SINCE)..$(GIT_VERSION))" > $@+
+	@echo "ChangeLog from $(GIT_URL) ($(log_range))" > $@+
 	@echo >> $@+
 	git log $(log_range) | sed -e 's/^/    /' >> $@+
 	mv $@+ $@
@@ -80,6 +77,7 @@ atom = <link rel="alternate" title="Atom feed" href="$(1)" \
 # using rdoc 2.4.1+
 doc: .document NEWS ChangeLog
 	for i in $(man1_bins); do > $$i; done
+	find bin lib -type f -name '*.rbc' -exec rm -f '{}' ';'
 	rdoc -Na -t "$(shell sed -ne '1s/^= //p' README)"
 	install -m644 COPYING doc/COPYING
 	install -m644 $(shell grep '^[A-Z]' .document)  doc/
@@ -94,8 +92,13 @@ doc: .document NEWS ChangeLog
 	$(RUBY) -i -p -e \
 	  '$$_.gsub!("</title>",%q{\&$(call atom,$(news_atom))})' \
 	  doc/NEWS.html doc/README.html
-	$(rake) -s news_atom > doc/NEWS.atom.xml
+	$(RAKE) -s news_atom > doc/NEWS.atom.xml
 	cd doc && ln README.html tmp && mv tmp index.html
+	$(MAKE) -C Documentation comparison.html
+	$(RUBY) -i -p -e \
+	  '$$_.gsub!(/INCLUDE/){File.read("Documentation/comparison.html")}' \
+	  doc/Summary.html
+	cat Documentation/comparison.css >> doc/rdoc.css
 	$(RM) $(man1_bins)
 
 ifneq ($(VERSION),)
@@ -109,10 +112,10 @@ release_changes := release_changes-$(VERSION)
 release-notes: $(release_notes)
 release-changes: $(release_changes)
 $(release_changes):
-	$(rake) -s release_changes > $@+
+	$(RAKE) -s release_changes > $@+
 	$(VISUAL) $@+ && test -s $@+ && mv $@+ $@
 $(release_notes):
-	GIT_URL=$(GIT_URL) $(rake) -s release_notes > $@+
+	GIT_URL=$(GIT_URL) $(RAKE) -s release_notes > $@+
 	$(VISUAL) $@+ && test -s $@+ && mv $@+ $@
 
 # ensures we're actually on the tagged $(VERSION), only used for release
@@ -150,10 +153,14 @@ $(pkgtgz): manifest fix-perms
 package: $(pkgtgz) $(pkggem)
 
 release: verify package $(release_notes) $(release_changes)
+	# make tgz release on RubyForge
 	rubyforge add_release -f -n $(release_notes) -a $(release_changes) \
 	  $(rfproject) $(rfpackage) $(VERSION) $(pkggem)
-	rubyforge add_file \
-	  $(rfproject) $(rfpackage) $(VERSION) $(pkgtgz)
+	# push gem to Gemcutter
+	gem push $(pkggem)
+	# in case of gem downloads from RubyForge releases page
+	-rubyforge add_file \
+	  $(rfproject) $(rfpackage) $(VERSION) $(pkggem)
 else
 gem install-gem: GIT-VERSION-FILE
 	$(MAKE) $@ VERSION=$(GIT_VERSION)

data/README

@@ -1,6 +1,6 @@
 = Rainbows! Unicorn for sleepy apps and slow clients
 
-Rainbows! is a HTTP server for sleepy Rack applications.  It is based on
+Rainbows! is an HTTP server for sleepy Rack applications.  It is based on
 Unicorn, but designed to handle applications that expect long
 request/response times and/or slow clients.  For Rack applications not
 heavily bound by slow external network dependencies, consider Unicorn
@@ -13,24 +13,23 @@ suck; differently.
 
 For network concurrency, models we currently support are:
 
-* {:Revactor}[link:Rainbows/Revactor.html]
-* {:ThreadPool}[link:Rainbows/ThreadPool.html]
-* {:Rev}[link:Rainbows/Rev.html]*
-* {:ThreadSpawn}[link:Rainbows/ThreadSpawn.html]
-* {:EventMachine}[link:Rainbows/EventMachine.html]
+* {Revactor}[link:Rainbows/Revactor.html]
+* {ThreadPool}[link:Rainbows/ThreadPool.html]
+* {Rev}[link:Rainbows/Rev.html]
+* {ThreadSpawn}[link:Rainbows/ThreadSpawn.html]
+* {EventMachine}[link:Rainbows/EventMachine.html]
+* {RevThreadSpawn}[link:Rainbows/RevThreadSpawn.html]
+* {FiberSpawn}[link:Rainbows/FiberSpawn.html]
+* {FiberPool}[link:Rainbows/FiberPool.html]
+* {NeverBlock}[link:Rainbows/NeverBlock.html]
 
-We have {more on the way}[link:TODO.html] for handling network concurrency.
-Additionally, we also use multiple processes (managed by Unicorn) for
-CPU/memory/disk concurrency.
+We have {many more on the way}[link:TODO.html] for handling network
+concurrency.  Additionally, we also use multiple processes (managed by
+Unicorn) for robustness and CPU/memory/disk concurrency.
 
-\* our \Rev concurrency model is only recommended for slow clients, not
-sleepy apps.  Additionally it does not support streaming "rack.input" to
-the application.
-
-For application concurrency, we have the Rainbows::AppPool Rack
-middleware that allows us to limit application concurrency independently
-of network concurrency.  Rack::Lock as distributed by Rack may also be
-used to limit application concurrency to one (per-worker).
+We also provide Rainbows::AppPool Rack middleware for some network
+concurrency models for limiting application concurrency independently of
+network concurrency.
 
 == Features
 
@@ -38,8 +37,8 @@ used to limit application concurrency to one (per-worker).
   modern Ruby HTTP applications.
 
 * Built on {Unicorn}[http://unicorn.bogomips.org/], inheriting its
-  process/socket management features
-  such as transparent upgrades and Ruby configuration DSL.
+  process/socket management features such as transparent upgrades and
+  Ruby configuration DSL.
 
 * As with Unicorn, it is able to stream large request bodies off the
   socket to the application while the client is still uploading.  Since
@@ -47,13 +46,16 @@ used to limit application concurrency to one (per-worker).
   it is with Unicorn.
 
 * Combines heavyweight concurrency (worker processes) with lightweight
-  concurrency (Actors or Threads), allowing CPU/memory/disk to be scaled
-  independently of client connections.  Alternative concurrency models
+  concurrency (Events/Fibers/Actors/Threads), allowing CPU/memory/disk to
+  be scaled independently of client connections.  More concurrency models
   (listed in the TODO) will be supported as we find time for them.
 
+* We give you {lots of options}[link:Summary.html] with more
+  {on the way}[link:TODO.html].
+
 == Applications
 
-\Rainbows is for the odd things Unicorn sucks at:
+\Rainbows is mainly designed for the odd things Unicorn sucks at:
 
 * 3rd-party APIs (to services outside your control/LAN)
 * OpenID consumers (to providers outside your control/LAN)
@@ -63,10 +65,12 @@ used to limit application concurrency to one (per-worker).
 * BOSH (with slow clients)
 * HTTP server push
 * Long polling
-* Reverse Ajax
+* Reverse AJAX
+* HTML 5 Web Sockets
+* real-time upload processing
 
-\Rainbows may also be used to service slow clients even with fast
-applications using the \Rev concurrency model.
+\Rainbows can also be used to service slow clients directly even with
+fast applications.
 
 == License
 
@@ -86,7 +90,7 @@ and run setup.rb after unpacking it:
 
 http://rubyforge.org/frs/?group_id=8977
 
-You may also install it via Rubygems on Rubyforge:
+You may also install it via RubyGems on Gemcutter:
 
   gem install rainbows
 
@@ -125,13 +129,13 @@ You can get the latest source via git from the following locations
 (these versions may not be stable):
 
   git://git.bogomips.org/rainbows.git
-  git://rubyforge.org/rainbows.git (mirror)
+  git://repo.or.cz/rainbows.git (mirror)
 
 You may browse the code from the web and download the latest snapshot
 tarballs here:
 
 * http://git.bogomips.org/cgit/rainbows.git (cgit)
-* http://rainbows.rubyforge.org/git?p=rainbows.git (gitweb)
+* http://repo.or.cz/w/rainbows.git (gitweb)
 
 Inline patches (from "git format-patch") to the mailing list are
 preferred because they allow code review and comments in the reply to