From 40cf3eb79054caa4b7d81120a736491aca8259eb Mon Sep 17 00:00:00 2001
From: Eric Wong <normalperson@yhbt.net>
Date: Thu, 28 Apr 2011 18:42:46 +0000
Subject: document epoll and xepoll

They're probably ready for general use in a very limited
capacity...
---
 Documentation/comparison.haml | 38 ++++++++++++++++++++++++++++++++++++++
 lib/rainbows/epoll.rb         | 21 ++++++++++++++++++---
 lib/rainbows/xepoll.rb        | 11 ++++++-----
 3 files changed, 62 insertions(+), 8 deletions(-)

diff --git a/Documentation/comparison.haml b/Documentation/comparison.haml
index 6a8f126..3289088 100644
--- a/Documentation/comparison.haml
+++ b/Documentation/comparison.haml
@@ -118,6 +118,20 @@
     %td.r19 Yes
     %td.rbx Yes
     %td.slow no
+  %tr.comp_row
+    %td.mod Epoll
+    %td.tee no
+    %td.r18 Yes
+    %td.r19 Yes
+    %td.rbx Yes
+    %td.slow Yes
+  %tr.comp_row
+    %td.mod XEpoll
+    %td.tee no
+    %td.r18 Yes
+    %td.r19 Yes
+    %td.rbx Yes
+    %td.slow Yes
 %ul
   %li
     Cool.io should also work with Rubinius (though we haven't had time to test).
@@ -232,6 +246,16 @@
     %td.slowio avoid
     %td.thr Maybe
     %td.reent Maybe
+  %tr.comp_base
+    %td.mod Epoll
+    %td.slowio No
+    %td.thr No
+    %td.reent No
+  %tr.comp_base
+    %td.mod XEpoll
+    %td.slowio No
+    %td.thr No
+    %td.reent No
 %ul
   %li
     Requirements for single thread reentrancy are loose in that there is
@@ -369,6 +393,20 @@
     %td.lock no-op
     %td.async Standard Ruby in response body only
     %td.ws response body only
+  %tr.comp_row
+    %td.mod Epoll
+    %td.devfd Yes
+    %td.app_pool no-op
+    %td.lock no-op
+    %td.async DevFdResponse
+    %td.ws no
+  %tr.comp_row
+    %td.mod XEpoll
+    %td.devfd Yes
+    %td.app_pool no-op
+    %td.lock no-op
+    %td.async DevFdResponse
+    %td.ws no
 %ul
   %li
     "No!" means it's fundamentally incompatible, use an
diff --git a/lib/rainbows/epoll.rb b/lib/rainbows/epoll.rb
index 075fcfb..599c969 100644
--- a/lib/rainbows/epoll.rb
+++ b/lib/rainbows/epoll.rb
@@ -1,11 +1,25 @@
 # -*- encoding: binary -*-
-# :enddoc:
 require 'sleepy_penguin'
 require 'sendfile'
 
-# Edge-triggered epoll concurrency model.  This is extremely unfair
-# and optimized for throughput at the expense of fairness
+# Edge-triggered epoll concurrency model using
+# {sleepy_penguin}[http://bogomips.org/sleepy_penguin/] for epoll.
+#
+# Unlike more portable options like Coolio and EventMachine, this
+# is Linux-only, but uses edge-triggering instead of level-triggering,
+# so it may perform better in some cases.  Coolio and EventMachine have
+# better library support and may be widely-used, however.
+#
+# Consider using XEpoll instead of this if you are using Ruby 1.9,
+# it will avoid accept()-scalability issues with many worker processes.
+#
+# When serving static files, this is extremely unfair and optimized
+# for throughput at the expense of fairness.  This is not an issue
+# if you're not serving static files, or if your working set is
+# small enough to aways be in your kernel page cache.  This concurrency
+# model may starve clients if you have slow disks and large static files.
 module Rainbows::Epoll
+  # :stopdoc:
   include Rainbows::Base
   ReRun = []
   autoload :Server, 'rainbows/epoll/server'
@@ -40,4 +54,5 @@ module Rainbows::Epoll
     init_worker_process(worker)
     Server.run
   end
+  # :startdoc:
 end
diff --git a/lib/rainbows/xepoll.rb b/lib/rainbows/xepoll.rb
index 3a02b46..2b38900 100644
--- a/lib/rainbows/xepoll.rb
+++ b/lib/rainbows/xepoll.rb
@@ -1,13 +1,13 @@
 # -*- encoding: binary -*-
-# :enddoc:
 require 'raindrops'
 require 'rainbows/epoll'
 
-# Edge-triggered epoll concurrency model with blocking accept() in
-# a (hopefully) native thread.  This is recommended over Epoll for
-# Ruby 1.9 users as it can workaround accept()-scalability issues
-# on multicore machines.
+# Edge-triggered epoll concurrency model with blocking accept() in a
+# (hopefully) native thread.  This is just like Epoll, but recommended
+# for Ruby 1.9 users as it can avoid accept()-scalability issues on
+# multicore machines with many worker processes.
 module Rainbows::XEpoll
+  # :stopdoc:
   include Rainbows::Base
   autoload :Client, 'rainbows/xepoll/client'
 
@@ -21,4 +21,5 @@ module Rainbows::XEpoll
     init_worker_process(worker)
     Client.run
   end
+  # :startdoc:
 end
-- 
cgit v1.2.3-24-ge0c7