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...
---
 lib/rainbows/epoll.rb  | 21 ++++++++++++++++++---
 lib/rainbows/xepoll.rb | 11 ++++++-----
 2 files changed, 24 insertions(+), 8 deletions(-)

(limited to 'lib')

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