Rev: general module documentation + caveats

1 files changed, 21 insertions, 0 deletions

diff --git a/lib/rainbows/rev.rb b/lib/rainbows/rev.rb
index 8cd76ae..8a575cd 100644
--- a/lib/rainbows/rev.rb
+++ b/lib/rainbows/rev.rb
@@ -7,6 +7,27 @@ defined?(Rev::Buffer) or Rev::Buffer = IO::Buffer
 
 module Rainbows
 
+  # Implements a basic single-threaded event model with
+  # {Rev}[http://rev.rubyforge.org/].  It is capable of handling
+  # 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).
+  #
+  # 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.
+  #
+  # 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.
   module Rev
 
     # global vars because class/instance variables are confusing me :<