huge documentation revamp

3 files changed, 34 insertions, 0 deletions

diff --git a/lib/rainbows/revactor.rb b/lib/rainbows/revactor.rb
index a20e09a..52cebf8 100644
--- a/lib/rainbows/revactor.rb
+++ b/lib/rainbows/revactor.rb
@@ -7,6 +7,20 @@ defined?(Rev::Buffer) or Rev::Buffer = IO::Buffer
 
 module Rainbows
 
+  # Enables use of the Actor model through
+  # {Revactor}[http://revactor.org] under Ruby 1.9.  It spawns one
+  # long-lived Actor for every listen socket in the process and spawns a
+  # new Actor for every client connection accept()-ed.
+  # +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
+  # sequentially (but at interleaved points).  Any network dependencies
+  # in the application using this model should be implemented using the
+  # \Revactor library as well.
+
   module Revactor
     require 'rainbows/revactor/tee_input'
 
diff --git a/lib/rainbows/thread_pool.rb b/lib/rainbows/thread_pool.rb
index 62a04a3..a6269cd 100644
--- a/lib/rainbows/thread_pool.rb
+++ b/lib/rainbows/thread_pool.rb
@@ -2,6 +2,18 @@
 
 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.
+  #
+  # Applications using this model are required to be thread-safe.
+  # Threads are never spawned dynamically under this model.  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.
+  #
+  # This model is 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 085da39..36968d8 100644
--- a/lib/rainbows/thread_spawn.rb
+++ b/lib/rainbows/thread_spawn.rb
@@ -1,6 +1,14 @@
 # -*- encoding: binary -*-
 module Rainbows
 
+  # Spawns a new thread for every client connection we accept().  This
+  # model is recommended for platforms where spawning threads is
+  # inexpensive.
+  #
+  # 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