about summary refs log tree commit homepage
path: root/lib/rainbows
diff options
context:
space:
mode:
authorEric Wong <normalperson@yhbt.net>2011-05-10 16:34:51 -0700
committerEric Wong <normalperson@yhbt.net>2011-05-10 16:34:51 -0700
commitd520222050ce88388ae5e446c63642d79cc9796e (patch)
tree5641847ef2726a3d66a36599f6d7b87def8f9c3b /lib/rainbows
parent95cec890409ac07d51c87ab157fe7e101d6f8432 (diff)
downloadrainbows-d520222050ce88388ae5e446c63642d79cc9796e.tar.gz
Finally, we have all methods in configurator and it's
much easier to document!
Diffstat (limited to 'lib/rainbows')
-rw-r--r--lib/rainbows/configurator.rb117
1 files changed, 77 insertions, 40 deletions
diff --git a/lib/rainbows/configurator.rb b/lib/rainbows/configurator.rb
index 95bb590..29d905b 100644
--- a/lib/rainbows/configurator.rb
+++ b/lib/rainbows/configurator.rb
@@ -2,6 +2,23 @@
 
 # This module adds \Rainbows! to the
 # {Unicorn::Configurator}[http://unicorn.bogomips.org/Unicorn/Configurator.html]
+# \Rainbows!-specific configuration options must be inside a the Rainbows!
+# block, otherwise Unicorn::Configurator directives may be used anwwhere
+# in the file.
+#
+#   Rainbows! do
+#     use :ThreadSpawn # concurrency model to use
+#     worker_connections 400
+#     keepalive_timeout 0 # zero disables keepalives entirely
+#     client_max_body_size 5*1024*1024 # 5 megabytes
+#     keepalive_requests 666 # default:100
+#     client_header_buffer_size 2 * 1024 # 2 kilobytes
+#   end
+#
+#   # the rest of the Unicorn configuration...
+#   worker_processes 8
+#   stderr_path "/path/to/error.log"
+#   stdout_path "/path/to/output.log"
 module Rainbows::Configurator
   Unicorn::Configurator::DEFAULTS.merge!({
     :use => Rainbows::Base,
@@ -12,45 +29,12 @@ module Rainbows::Configurator
     :client_header_buffer_size => 1024,
   })
 
-  # configures \Rainbows! with a given concurrency model to +use+ and
-  # a +worker_connections+ upper-bound.  This method may be called
-  # inside a Unicorn/\Rainbows! configuration file:
+  # Configures \Rainbows! with a given concurrency model to +use+ and
+  # a +worker_connections+ upper-bound.  This method should be called
+  # inside a Unicorn/\Rainbows! configuration file.
   #
-  #   Rainbows! do
-  #     use :ThreadSpawn # concurrency model to use
-  #     worker_connections 400
-  #     keepalive_timeout 0 # zero disables keepalives entirely
-  #     client_max_body_size 5*1024*1024 # 5 megabytes
-  #     keepalive_requests 666 # default:100
-  #     client_header_buffer_size 16 * 1024 # 16 kilobytes
-  #   end
-  #
-  #   # the rest of the Unicorn configuration
-  #   worker_processes 8
-  #
-  # See the documentation for the respective Revactor, ThreadSpawn,
-  # and ThreadPool classes for descriptions and recommendations for
-  # each of them.  The total number of clients we're able to serve is
-  # +worker_processes+ * +worker_connections+, so in the above example
-  # we can serve 8 * 400 = 3200 clients concurrently.
-  #
-  # The default is +keepalive_timeout+ is 5 seconds, which should be
-  # enough under most conditions for browsers to render the page and
-  # start retrieving extra elements for.  Increasing this beyond 5
-  # seconds is not recommended.  Zero disables keepalive entirely
-  # (but pipelining fully-formed requests is still works).
-  #
-  # The default +client_max_body_size+ is 1 megabyte (1024 * 1024 bytes),
-  # setting this to +nil+ will disable body size checks and allow any
-  # size to be specified.
-  #
-  # The default +keepalive_requests+ is 100, meaning a client may
-  # complete 100 keepalive requests after the initial request before
-  # \Rainbows! forces a disconnect.  Lowering this can improve
-  # load-balancing characteristics as it forces HTTP/1.1 clients to
-  # reconnect after the specified number of requests, hopefully to a
-  # less busy host or worker process.  This may also be used to mitigate
-  # denial-of-service attacks that use HTTP pipelining.
+  # All other methods in Rainbows::Configurator must be called
+  # inside this block.
   def Rainbows!(&block)
     block_given? or raise ArgumentError, "Rainbows! requires a block"
     @block = true
@@ -63,11 +47,31 @@ module Rainbows::Configurator
     @block or abort "must be inside a Rainbows! block"
   end
 
-  def worker_connections(nr)
+  # This limits the number of connected clients per-process.  The total
+  # number of clients on a server is +worker_processes+ * +worker_connections+.
+  #
+  # This option has no effect with the Base concurrency model, which is
+  # limited to +1+.
+  #
+  # Default: 50
+  def worker_connections(clients)
     check!
-    set_int(:worker_connections, nr, 1)
+    set_int(:worker_connections, clients, 1)
   end
 
+  # Select a concurrency model for use with \Rainbows!.  You must select
+  # this with a Symbol (prefixed with ":").  Thus if you wish to select
+  # the Rainbows::ThreadSpawn concurrency model, you would use:
+  #
+  #   Rainbows! do
+  #     use :ThreadSpawn
+  #   end
+  #
+  # See the {Summary}[link:Summary.html] document for a summary of
+  # supported concurrency models.  +options+ may be specified for some
+  # concurrency models, but the majority do not support them.
+  #
+  # Default: :Base (no concurrency)
   def use(model, *options)
     check!
     mod = begin
@@ -92,11 +96,26 @@ module Rainbows::Configurator
     set[:use] = mod
   end
 
+  # Sets the value (in seconds) the server will wait for a client in
+  # between requests.  The default value should be enough under most
+  # conditions for browsers to render the page and start retrieving
+  # extra elements.
+  #
+  # Setting this value to +0+ disables keepalive entirely
+  #
+  # Default: 5 seconds
   def keepalive_timeout(seconds)
     check!
     set_int(:keepalive_timeout, seconds, 0)
   end
 
+  # This limits the number of requests which can be made over a keep-alive
+  # connection.  This is used to prevent single client from monopolizing
+  # the server and to improve fairness when load-balancing across multiple
+  # machines by forcing a client to reconnect.  This may be helpful
+  # in mitigating some denial-of-service attacks.
+  #
+  # Default: 100 requests
   def keepalive_requests(count)
     check!
     case count
@@ -107,6 +126,13 @@ module Rainbows::Configurator
     end
   end
 
+  # Limits the maximum size of a request body for all requests.
+  # Setting this to +nil+ disables the maximum size check.
+  #
+  # Default: 1 megabyte (1048576 bytes)
+  #
+  # If you want endpoint-specific upload limits and use a
+  # "rack.input"-streaming concurrency model, see the Rainbows::MaxBody
   def client_max_body_size(bytes)
     check!
     err = "client_max_body_size must be nil or a non-negative Integer"
@@ -120,6 +146,17 @@ module Rainbows::Configurator
     set[:client_max_body_size] = bytes
   end
 
+  # This governs the amount of memory allocated for an individual read(2) or
+  # recv(2) system call when reading headers.  Applications that make minimal
+  # use of cookies should not increase this from the default.
+  #
+  # Rails applications using session cookies may want to increase this to
+  # 2048 bytes or more depending on expected request sizes.
+  #
+  # Increasing this will increase overall memory usage to your application,
+  # as you will need at least this amount of memory for every connected client.
+  #
+  # Default: 1024 bytes
   def client_header_buffer_size(bytes)
     check!
     set_int(:client_header_buffer_size, bytes, 1)