about summary refs log tree commit homepage
diff options
context:
space:
mode:
authorEric Wong <normalperson@yhbt.net>2011-05-09 01:57:16 +0000
committerEric Wong <normalperson@yhbt.net>2011-05-09 01:57:16 +0000
commitd0336075a772d040b9fe3100098e1815ce609cb4 (patch)
tree25da2a2812aab998e85e2cd3342bf2183f805dea
parenta62e9240fffe544d171c87f94946ecf50888a6df (diff)
downloadrainbows-d0336075a772d040b9fe3100098e1815ce609cb4.tar.gz
It's good to describe what they're useful for.
-rw-r--r--lib/rainbows/xepoll_thread_pool.rb46
-rw-r--r--lib/rainbows/xepoll_thread_spawn.rb35
2 files changed, 79 insertions, 2 deletions
diff --git a/lib/rainbows/xepoll_thread_pool.rb b/lib/rainbows/xepoll_thread_pool.rb
index b6eb55d..9107b5d 100644
--- a/lib/rainbows/xepoll_thread_pool.rb
+++ b/lib/rainbows/xepoll_thread_pool.rb
@@ -3,10 +3,52 @@ require "thread"
 require "sleepy_penguin"
 require "raindrops"
 
+# This is an edge-triggered epoll concurrency model with blocking
+# accept() in a (hopefully) native thread.  This is comparable to
+# ThreadPool and CoolioThreadPool, but is Linux-only and able to exploit
+# "wake one" accept() behavior of a blocking accept() call when used
+# with native threads.
+#
+# This supports streaming "rack.input" and allows +:pool_size+ tuning
+# independently of +worker_connections+
+#
+# === Disadvantages
+#
+# This is only supported under Linux 2.6 kernels.
+#
+# === Compared to CoolioThreadPool
+#
+# This does not buffer outgoing responses in userspace at all, meaning
+# it can lower response latency to fast clients and also prevent
+# starvation of other clients when reading slow disks for responses
+# (when combined with native threads).
+#
+# CoolioThreadPool is likely better for trickling large static files or
+# proxying responses to slow clients, but this is likely better for fast
+# clients.
+#
+# Unlikely CoolioThreadPool, this supports streaming "rack.input" which
+# is useful for reading large uploads from fast clients.
+#
+# This exposes no special API or extensions on top of Rack.
+#
+# === Compared to ThreadPool
+#
+# This can maintain idle connections without the memory overhead of an
+# idle Thread.  The cost of handling/dispatching active connections is
+# exactly the same for an equivalent number of active connections
+# (but independently tunable).
+#
+# Since +:pool_size+ and +worker_connections+ is independently tunable,
+# it is possible to get into situations where active connections need
+# to wait for an idle thread in the thread pool before being processed
+
 module Rainbows::XEpollThreadPool
-  include Rainbows::Base
   extend Rainbows::PoolSize
 
+  # :stopdoc:
+  include Rainbows::Base
+
   def init_worker_process(worker)
     super
     require "rainbows/xepoll_thread_pool/client"
@@ -17,5 +59,5 @@ module Rainbows::XEpollThreadPool
     init_worker_process(worker)
     Client.loop
   end
+  # :startdoc:
 end
-
diff --git a/lib/rainbows/xepoll_thread_spawn.rb b/lib/rainbows/xepoll_thread_spawn.rb
index ad2bdc4..d94cf48 100644
--- a/lib/rainbows/xepoll_thread_spawn.rb
+++ b/lib/rainbows/xepoll_thread_spawn.rb
@@ -3,7 +3,41 @@ require "thread"
 require "sleepy_penguin"
 require "raindrops"
 
+# This is an edge-triggered epoll concurrency model with blocking
+# accept() in a (hopefully) native thread.  This is comparable to
+# ThreadSpawn and CoolioThreadSpawn, but is Linux-only and able to exploit
+# "wake one" accept() behavior of a blocking accept() call when used
+# with native threads.
+#
+# This supports streaming "rack.input" and allows +:pool_size+ tuning
+# independently of +worker_connections+
+#
+# === Disadvantages
+#
+# This is only supported under Linux 2.6 kernels.
+#
+# === Compared to CoolioThreadSpawn
+#
+# This does not buffer outgoing responses in userspace at all, meaning
+# it can lower response latency to fast clients and also prevent
+# starvation of other clients when reading slow disks for responses
+# (when combined with native threads).
+#
+# CoolioThreadSpawn is likely better for trickling large static files or
+# proxying responses to slow clients, but this is likely better for fast
+# clients.
+#
+# Unlikely CoolioThreadSpawn, this supports streaming "rack.input" which
+# is useful for reading large uploads from fast clients.
+#
+# === Compared to ThreadSpawn
+#
+# This can maintain idle connections without the memory overhead of an
+# idle Thread.  The cost of handling/dispatching active connections is
+# exactly the same for an equivalent number of active connections.
+
 module Rainbows::XEpollThreadSpawn
+  # :stopdoc:
   include Rainbows::Base
 
   def init_worker_process(worker)
@@ -16,4 +50,5 @@ module Rainbows::XEpollThreadSpawn
     init_worker_process(worker)
     Client.loop
   end
+  # :startdoc:
 end