From b14f5bcec7d9864faed7fcb06028eafe89a4a722 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Wed, 14 Oct 2009 18:25:15 -0700 Subject: documentation updates (mostly on network models) --- README | 6 ++++++ TODO | 5 ++--- lib/rainbows/rev.rb | 19 +++++++++++-------- lib/rainbows/revactor.rb | 10 ++++++---- lib/rainbows/thread_pool.rb | 15 +++++++++++---- lib/rainbows/thread_spawn.rb | 10 ++++++++-- 6 files changed, 44 insertions(+), 21 deletions(-) diff --git a/README b/README index 8924891..879365c 100644 --- a/README +++ b/README @@ -16,11 +16,17 @@ For network concurrency, models we currently support are: * {:ThreadSpawn}[link:Rainbows/ThreadSpawn.html] * {:ThreadPool}[link:Rainbows/ThreadPool.html] * {:Revactor}[link:Rainbows/Revactor.html] +* {:Rev}[link:Rainbows/Rev.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. +\* the \Rev concurrency model does not support streaming "rack.input" to +the application. All other models support a streaming "rack.input" which +allows the Rack application to read data as it arrives on the socket +without fully buffering it first. + == Features * Designed for {Rack}[http://rack.rubyforge.org/], the standard for diff --git a/TODO b/TODO index 2c90a09..553e511 100644 --- a/TODO +++ b/TODO @@ -3,9 +3,8 @@ We're lazy and pick the easy items to do first, then the ones people care about. -* Rev (without Revactor) - since we already use Revactor we might as - well support this one so 1.8 users won't be left out. Doing TeeInput - is probably going to get ugly, though... +* Rev + Thread - current Rev model with threading, which will give + us a streaming (but rewindable) "rack.input". * EventMachine - much like Rev, but we haven't looked at this one much (our benevolent dictator doesn't like C++). If we can figure out how diff --git a/lib/rainbows/rev.rb b/lib/rainbows/rev.rb index abdc326..8381975 100644 --- a/lib/rainbows/rev.rb +++ b/lib/rainbows/rev.rb @@ -12,22 +12,25 @@ module Rainbows # thousands of simultaneous client connections, but with only a # single-threaded app dispatch. It is suited for slow clients and # fast applications (applications that do not have slow network - # dependencies). + # dependencies). It does not require your Rack application to + # be reentrant or thread-safe. # - # Compatibility: Whatever \Rev itself supports, currently Ruby 1.8/1.9. + # Compatibility: Whatever \Rev itself supports, currently Ruby + # 1.8/1.9. # - # This model does not implement TeeInput for streaming requests to - # the Rack application. This means env["rack.input"] will - # be fully buffered in memory or to a temporary file before the - # application is called. + # This model does not implement as streaming "rack.input" which + # allows the Rack application to process data as it arrives. This + # means "rack.input" will be fully buffered in memory or to a + # temporary file before the application is entered. # # Caveats: this model can buffer all output for slow clients in # memory. This can be a problem if your application generates large # responses (including static files served with Rack) as it will cause # the memory footprint of your process to explode. If your workers # seem to be eating a lot of memory from this, consider the - # {mall}[http://bogomips.org/mall/] library which allows access to - # the mallopt(3) in the standard C library from Ruby. + # {mall}[http://bogomips.org/mall/] library which allows access to the + # mallopt(3) function from Ruby. + module Rev # global vars because class/instance variables are confusing me :< diff --git a/lib/rainbows/revactor.rb b/lib/rainbows/revactor.rb index fb35394..f61de97 100644 --- a/lib/rainbows/revactor.rb +++ b/lib/rainbows/revactor.rb @@ -14,12 +14,14 @@ module Rainbows # +worker_connections+ will limit the number of client Actors we have # running at any one time. # - # Applications using this model are required to be reentrant, but - # generally do not have to worry about race conditions. Multiple - # instances of the same app may run in the same address space + # Applications using this model are required to be reentrant, but do + # not have to worry about race conditions unless they use threads + # internally. \Rainbows! does not spawn threads under this model. + # Multiple instances of the same app may run in the same address space # sequentially (but at interleaved points). Any network dependencies # in the application using this model should be implemented using the - # \Revactor library as well. + # \Revactor library as well, to take advantage of the networking + # concurrency features this model provides. module Revactor require 'rainbows/revactor/tee_input' diff --git a/lib/rainbows/thread_pool.rb b/lib/rainbows/thread_pool.rb index 50d0322..d7f0b14 100644 --- a/lib/rainbows/thread_pool.rb +++ b/lib/rainbows/thread_pool.rb @@ -3,8 +3,14 @@ module Rainbows # Implements a worker thread pool model. This is suited for platforms - # where the cost of dynamically spawning a new thread for every new - # client connection is too high. + # like Ruby 1.9, where the cost of dynamically spawning a new thread + # for every new client connection is higher than with the ThreadSpawn + # model. + # + # This model should provide a high level of compatibility with all + # Ruby implementations, and most libraries and applications. + # Applications running under this model should be thread-safe + # but not necessarily reentrant. # # Applications using this model are required to be thread-safe. # Threads are never spawned dynamically under this model. If you're @@ -12,8 +18,9 @@ module Rainbows # consider using the "resolv-replace" library which replaces parts of # the core Socket package with concurrent DNS lookup capabilities. # - # This model is less suited for many slow clients than the others and - # thus a lower +worker_connections+ setting is recommended. + # This model probably less suited for many slow clients than the + # others and thus a lower +worker_connections+ setting is recommended. + module ThreadPool include Base diff --git a/lib/rainbows/thread_spawn.rb b/lib/rainbows/thread_spawn.rb index f14ed1c..d002c81 100644 --- a/lib/rainbows/thread_spawn.rb +++ b/lib/rainbows/thread_spawn.rb @@ -2,13 +2,19 @@ module Rainbows # Spawns a new thread for every client connection we accept(). This - # model is recommended for platforms where spawning threads is - # inexpensive. + # model is recommended for platforms like Ruby 1.8 where spawning new + # threads is inexpensive. + # + # This model should provide a high level of compatibility with all + # Ruby implementations, and most libraries and applications. + # Applications running under this model should be thread-safe + # but not necessarily reentrant. # # If you're connecting to external services and need to perform DNS # lookups, consider using the "resolv-replace" library which replaces # parts of the core Socket package with concurrent DNS lookup # capabilities + module ThreadSpawn include Base -- cgit v1.2.3-24-ge0c7