From d0336075a772d040b9fe3100098e1815ce609cb4 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Mon, 9 May 2011 01:57:16 +0000 Subject: xepoll_thread_*: add rdoc for users It's good to describe what they're useful for. --- lib/rainbows/xepoll_thread_pool.rb | 46 +++++++++++++++++++++++++++++++++++-- lib/rainbows/xepoll_thread_spawn.rb | 35 ++++++++++++++++++++++++++++ 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 -- cgit v1.2.3-24-ge0c7