huge documentation revamp

1 files changed, 12 insertions, 0 deletions

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