documentation updates (mostly on network models)

4 files changed, 36 insertions, 18 deletions

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