unicorn-academia 4.7.0.1

data/DESIGN

@@ -0,0 +1,97 @@
+== Design
+
+* Simplicity: Unicorn is a traditional UNIX prefork web server.
+  No threads are used at all, this makes applications easier to debug
+  and fix.  When your application goes awry, a BOFH can just
+  "kill -9" the runaway worker process without worrying about tearing
+  all clients down, just one.  Only UNIX-like systems supporting
+  fork() and file descriptor inheritance are supported.
+
+* The Ragel+C HTTP parser is taken from Mongrel.  This is the
+  only non-Ruby part and there are no plans to add any more
+  non-Ruby components.
+
+* All HTTP parsing and I/O is done much like Mongrel:
+    1. read/parse HTTP request headers in full
+    2. call Rack application
+    3. write HTTP response back to the client
+
+* Like Mongrel, neither keepalive nor pipelining are supported.
+  These aren't needed since Unicorn is only designed to serve
+  fast, low-latency clients directly.  Do one thing, do it well;
+  let nginx handle slow clients.
+
+* Configuration is purely in Ruby and eval().  Ruby is less
+  ambiguous than YAML and lets lambdas for
+  before_fork/after_fork/before_exec hooks be defined inline.  An
+  optional, separate config_file may be used to modify supported
+  configuration changes (and also gives you plenty of rope if you RTFS
+  :>)
+
+* One master process spawns and reaps worker processes.  The
+  Rack application itself is called only within the worker process (but
+  can be loaded within the master).  A copy-on-write friendly garbage
+  collector like the one found in Ruby 2.0.0dev or Ruby Enterprise Edition
+  can be used to minimize memory usage along with the "preload_app true"
+  directive (see Unicorn::Configurator).
+
+* The number of worker processes should be scaled to the number of
+  CPUs, memory or even spindles you have.  If you have an existing
+  Mongrel cluster on a single-threaded app, using the same amount of
+  processes should work.  Let a full-HTTP-request-buffering reverse
+  proxy like nginx manage concurrency to thousands of slow clients for
+  you.  Unicorn scaling should only be concerned about limits of your
+  backend system(s).
+
+* Load balancing between worker processes is done by the OS kernel.
+  All workers share a common set of listener sockets and does
+  non-blocking accept() on them.  The kernel will decide which worker
+  process to give a socket to and workers will sleep if there is
+  nothing to accept().
+
+* Since non-blocking accept() is used, there can be a thundering
+  herd when an occasional client connects when application
+  *is not busy*.  The thundering herd problem should not affect
+  applications that are running all the time since worker processes
+  will only select()/accept() outside of the application dispatch.
+
+* Additionally, thundering herds are much smaller than with
+  configurations using existing prefork servers.  Process counts should
+  only be scaled to backend resources, _never_ to the number of expected
+  clients like is typical with blocking prefork servers.  So while we've
+  seen instances of popular prefork servers configured to run many
+  hundreds of worker processes, Unicorn deployments are typically only
+  2-4 processes per-core.
+
+* On-demand scaling of worker processes never happens automatically.
+  Again, Unicorn is concerned about scaling to backend limits and should
+  never configured in a fashion where it could be waiting on slow
+  clients.  For extremely rare circumstances, we provide TTIN and TTOU
+  signal handlers to increment/decrement your process counts without
+  reloading.  Think of it as driving a car with manual transmission:
+  you have a lot more control if you know what you're doing.
+
+* Blocking I/O is used for clients.  This allows a simpler code path
+  to be followed within the Ruby interpreter and fewer syscalls.
+  Applications that use threads continue to work if Unicorn
+  is only serving LAN or localhost clients.
+
+* SIGKILL is used to terminate the timed-out workers from misbehaving apps
+  as reliably as possible on a UNIX system.  The default timeout is a
+  generous 60 seconds (same default as in Mongrel).
+
+* The poor performance of select() on large FD sets is avoided
+  as few file descriptors are used in each worker.
+  There should be no gain from moving to highly scalable but
+  unportable event notification solutions for watching few
+  file descriptors.
+
+* If the master process dies unexpectedly for any reason,
+  workers will notice within :timeout/2 seconds and follow
+  the master to its death.
+
+* There is never any explicit real-time dependency or communication
+  between the worker processes nor to the master process.
+  Synchronization is handled entirely by the OS kernel and shared
+  resources are never accessed by the worker when it is servicing
+  a client.

data/Documentation/.gitignore

@@ -0,0 +1,5 @@
+*.1
+*.5
+*.7
+*.gz
+*.html

data/Documentation/GNUmakefile

@@ -0,0 +1,30 @@
+all::
+
+PANDOC = pandoc
+PANDOC_OPTS = -f markdown --email-obfuscation=none
+pandoc = $(PANDOC) $(PANDOC_OPTS)
+pandoc_html = $(pandoc) --toc -t html --no-wrap
+
+man1 := $(addsuffix .1,unicorn unicorn_rails)
+html1 := $(addsuffix .html,$(man1))
+
+all:: html man
+
+html: $(html1)
+man: $(man1)
+
+install-html: html
+	mkdir -p ../doc/man1
+	install -m 644 $(html1) ../doc/man1
+
+install-man: man
+	mkdir -p ../man/man1
+	install -m 644 $(man1) ../man/man1
+
+%.1: %.1.txt
+	$(pandoc) -s -t man < $< > $@+ && mv $@+ $@
+%.1.html: %.1.txt
+	$(pandoc_html) < $< > $@+ && mv $@+ $@
+
+clean::
+	$(RM) $(man1) $(html1)

data/Documentation/unicorn.1.txt

@@ -0,0 +1,178 @@
+% UNICORN(1) Unicorn User Manual
+% The Unicorn Community <mongrel-unicorn@rubyforge.org>
+% September 15, 2009
+
+# NAME
+
+unicorn - a rackup-like command to launch the Unicorn HTTP server
+
+# SYNOPSIS
+
+unicorn [-c CONFIG_FILE] [-E RACK_ENV] [-D] [RACKUP_FILE]
+
+# DESCRIPTION
+
+A rackup(1)-like command to launch Rack applications using Unicorn.
+It is expected to be started in your application root (APP_ROOT),
+but the "working_directory" directive may be used in the CONFIG_FILE.
+
+While unicorn takes a myriad of command-line options for
+compatibility with ruby(1) and rackup(1), it is recommended to stick
+to the few command-line options specified in the SYNOPSIS and use
+the CONFIG_FILE as much as possible.
+
+# RACKUP FILE
+
+This defaults to \"config.ru\" in APP_ROOT.  It should be the same
+file used by rackup(1) and other Rack launchers, it uses the
+*Rack::Builder* DSL.
+
+Embedded command-line options are mostly parsed for compatibility
+with rackup(1) but strongly discouraged.
+
+# UNICORN OPTIONS
+-c, \--config-file CONFIG_FILE
+:   Path to the Unicorn-specific config file.  The config file is
+    implemented as a Ruby DSL, so Ruby code may executed.
+    See the RDoc/ri for the *Unicorn::Configurator* class for the full
+    list of directives available from the DSL.
+    Using an absolute path for for CONFIG_FILE is recommended as it
+    makes multiple instances of Unicorn easily distinguishable when
+    viewing ps(1) output.
+
+-D, \--daemonize
+:   Run daemonized in the background.  The process is detached from
+    the controlling terminal and stdin is redirected to "/dev/null".
+    Unlike many common UNIX daemons, we do not chdir to \"/\"
+    upon daemonization to allow more control over the startup/upgrade
+    process.
+    Unless specified in the CONFIG_FILE, stderr and stdout will
+    also be redirected to "/dev/null".
+
+-E, \--env RACK_ENV
+:   Run under the given RACK_ENV.  See the RACK ENVIRONMENT section
+    for more details.
+
+-l, \--listen ADDRESS
+:   Listens on a given ADDRESS.  ADDRESS may be in the form of
+    HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
+    and PATH is meant to be a path to a UNIX domain socket.
+    Defaults to "0.0.0.0:8080" (all addresses on TCP port 8080)
+    For production deployments, specifying the "listen" directive in
+    CONFIG_FILE is recommended as it allows fine-tuning of socket
+    options.
+-N, \--no-default-middleware
+:   Disables loading middleware implied by RACK_ENV.  This bypasses the
+    configuration documented in the RACK ENVIRONMENT section, but still
+    allows RACK_ENV to be used for application/framework-specific purposes.
+
+# RACKUP COMPATIBILITY OPTIONS
+-o, \--host HOST
+:   Listen on a TCP socket belonging to HOST, default is
+    "0.0.0.0" (all addresses).
+    If specified multiple times on the command-line, only the
+    last-specified value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+-p, \--port PORT
+:   Listen on the specified TCP PORT, default is 8080.
+    If specified multiple times on the command-line, only the last-specified
+    value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+-s, \--server SERVER
+:   No-op, this exists only for compatibility with rackup(1).
+
+# RUBY OPTIONS
+-e, \--eval LINE
+:   Evaluate a LINE of Ruby code.  This evaluation happens
+    immediately as the command-line is being parsed.
+
+-d, \--debug
+:   Turn on debug mode, the $DEBUG variable is set to true.
+
+-w, \--warn
+:   Turn on verbose warnings, the $VERBOSE variable is set to true.
+
+-I, \--include PATH
+:   specify $LOAD_PATH.  PATH will be prepended to $LOAD_PATH.
+    The \':\' character may be used to delimit multiple directories.
+    This directive may be used more than once.  Modifications to
+    $LOAD_PATH take place immediately and in the order they were
+    specified on the command-line.
+
+-r, \--require LIBRARY
+:   require a specified LIBRARY before executing the application.  The
+    \"require\" statement will be executed immediately and in the order
+    they were specified on the command-line.
+
+# SIGNALS
+
+The following UNIX signals may be sent to the master process:
+
+* HUP - reload config file, app, and gracefully restart all workers
+* INT/TERM - quick shutdown, kills all workers immediately
+* QUIT - graceful shutdown, waits for workers to finish their
+  current request before finishing.
+* USR1 - reopen all logs owned by the master and all workers
+  See Unicorn::Util.reopen_logs for what is considered a log.
+* USR2 - reexecute the running binary.  A separate QUIT
+  should be sent to the original process once the child is verified to
+  be up and running.
+* WINCH - gracefully stops workers but keep the master running.
+  This will only work for daemonized processes.
+* TTIN - increment the number of worker processes by one
+* TTOU - decrement the number of worker processes by one
+
+See the [SIGNALS][4] document for full description of all signals
+used by Unicorn.
+
+#  RACK ENVIRONMENT
+
+Accepted values of RACK_ENV and the middleware they automatically load
+(outside of RACKUP_FILE) are exactly as those in rackup(1):
+
+* development - loads Rack::CommonLogger, Rack::ShowExceptions, and
+                Rack::Lint middleware
+* deployment  - loads Rack::CommonLogger middleware
+* none        - loads no middleware at all, relying
+                entirely on RACKUP_FILE
+
+All unrecognized values for RACK_ENV are assumed to be
+"none".  Production deployments are strongly encouraged to use
+"deployment" or "none" for maximum performance.
+
+As of Unicorn 0.94.0, RACK_ENV is exported as a process-wide environment
+variable as well.  While not current a part of the Rack specification as
+of Rack 1.0.1, this has become a de facto standard in the Rack world.
+
+Note the Rack::ContentLength and Rack::Chunked middlewares are also
+loaded by "deployment" and "development", but no other values of
+RACK_ENV.  If needed, they must be individually specified in the
+RACKUP_FILE, some frameworks do not require them.
+
+# ENVIRONMENT VARIABLES
+
+The RACK_ENV variable is set by the aforementioned \-E switch.
+All application or library-specific environment variables (e.g. TMPDIR)
+may always be set in the Unicorn CONFIG_FILE in addition to the spawning
+shell.  When transparently upgrading Unicorn, all environment variables
+set in the old master process are inherited by the new master process.
+Unicorn only uses (and will overwrite) the UNICORN_FD environment
+variable internally when doing transparent upgrades.
+
+# SEE ALSO
+
+* unicorn_rails(1)
+* *Rack::Builder* ri/RDoc
+* *Unicorn::Configurator* ri/RDoc
+* [Unicorn RDoc][1]
+* [Rack RDoc][2]
+* [Rackup HowTo][3]
+
+[1]: http://unicorn.bogomips.org/
+[2]: http://rack.rubyforge.org/doc/
+[3]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
+[4]: http://unicorn.bogomips.org/SIGNALS.html

data/Documentation/unicorn_rails.1.txt

@@ -0,0 +1,175 @@
+% UNICORN_RAILS(1) Unicorn User Manual
+% The Unicorn Community <mongrel-unicorn@rubyforge.org>
+% September 17, 2009
+
+# NAME
+
+unicorn_rails - a script/server-like command to launch the Unicorn HTTP server
+
+# SYNOPSIS
+
+unicorn_rails [-c CONFIG_FILE] [-E RAILS_ENV] [-D] [RACKUP_FILE]
+
+# DESCRIPTION
+
+A rackup(1)-like command to launch Rails applications using Unicorn.  It
+is expected to be started in your Rails application root (RAILS_ROOT),
+but the "working_directory" directive may be used in the CONFIG_FILE.
+
+It is designed to help Rails 1.x and 2.y users transition to Rack, but
+it is NOT needed for Rails 3 applications.  Rails 3 users are encouraged
+to use unicorn(1) instead of unicorn_rails(1).  Users of Rails 1.x/2.y
+may also use unicorn(1) instead of unicorn_rails(1).
+
+The outward interface resembles rackup(1), the internals and default
+middleware loading is designed like the `script/server` command
+distributed with Rails.
+
+While Unicorn takes a myriad of command-line options for compatibility
+with ruby(1) and rackup(1), it is recommended to stick to the few
+command-line options specified in the SYNOPSIS and use the CONFIG_FILE
+as much as possible.
+
+# UNICORN OPTIONS
+-c, \--config-file CONFIG_FILE
+:   Path to the Unicorn-specific config file.  The config file is
+    implemented as a Ruby DSL, so Ruby code may executed.
+    See the RDoc/ri for the *Unicorn::Configurator* class for the full
+    list of directives available from the DSL.
+    Using an absolute path for for CONFIG_FILE is recommended as it
+    makes multiple instances of Unicorn easily distinguishable when
+    viewing ps(1) output.
+
+-D, \--daemonize
+:   Run daemonized in the background.  The process is detached from
+    the controlling terminal and stdin is redirected to "/dev/null".
+    Unlike many common UNIX daemons, we do not chdir to \"/\"
+    upon daemonization to allow more control over the startup/upgrade
+    process.
+    Unless specified in the CONFIG_FILE, stderr and stdout will
+    also be redirected to "/dev/null".
+    Daemonization will _skip_ loading of the *Rails::Rack::LogTailer*
+    middleware under Rails \>\= 2.3.x.
+    By default, unicorn\_rails(1) will create a PID file in
+    _\"RAILS\_ROOT/tmp/pids/unicorn.pid\"_.  You may override this
+    by specifying the "pid" directive to override this Unicorn config file.
+
+-E, \--env RAILS_ENV
+:   Run under the given RAILS_ENV.  This sets the RAILS_ENV environment
+    variable.  Acceptable values are exactly those you expect in your Rails
+    application, typically "development" or "production".
+
+-l, \--listen ADDRESS
+:   Listens on a given ADDRESS.  ADDRESS may be in the form of
+    HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
+    and PATH is meant to be a path to a UNIX domain socket.
+    Defaults to "0.0.0.0:8080" (all addresses on TCP port 8080).
+    For production deployments, specifying the "listen" directive in
+    CONFIG_FILE is recommended as it allows fine-tuning of socket
+    options.
+
+# RACKUP COMPATIBILITY OPTIONS
+-o, \--host HOST
+:   Listen on a TCP socket belonging to HOST, default is
+    "0.0.0.0" (all addresses).
+    If specified multiple times on the command-line, only the
+    last-specified value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+-p, \--port PORT
+:   Listen on the specified TCP PORT, default is 8080.
+    If specified multiple times on the command-line, only the last-specified
+    value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+\--path PATH
+:   Mounts the Rails application at the given PATH (instead of "/").
+    This is equivalent to setting the RAILS_RELATIVE_URL_ROOT
+    environment variable.  This is only supported under Rails 2.3
+    or later at the moment.
+
+# RUBY OPTIONS
+-e, \--eval LINE
+:   Evaluate a LINE of Ruby code.  This evaluation happens
+    immediately as the command-line is being parsed.
+
+-d, \--debug
+:   Turn on debug mode, the $DEBUG variable is set to true.
+    For Rails \>\= 2.3.x, this loads the *Rails::Rack::Debugger*
+    middleware.
+
+-w, \--warn
+:   Turn on verbose warnings, the $VERBOSE variable is set to true.
+
+-I, \--include PATH
+:   specify $LOAD_PATH.  PATH will be prepended to $LOAD_PATH.
+    The \':\' character may be used to delimit multiple directories.
+    This directive may be used more than once.  Modifications to
+    $LOAD_PATH take place immediately and in the order they were
+    specified on the command-line.
+
+-r, \--require LIBRARY
+:   require a specified LIBRARY before executing the application.  The
+    \"require\" statement will be executed immediately and in the order
+    they were specified on the command-line.
+
+# RACKUP FILE
+
+This defaults to \"config.ru\" in RAILS_ROOT.  It should be the same
+file used by rackup(1) and other Rack launchers, it uses the
+*Rack::Builder* DSL.  Unlike many other Rack applications, RACKUP_FILE
+is completely _optional_ for Rails, but may be used to disable some
+of the default middleware for performance.
+
+Embedded command-line options are mostly parsed for compatibility
+with rackup(1) but strongly discouraged.
+
+# ENVIRONMENT VARIABLES
+
+The RAILS_ENV variable is set by the aforementioned \-E switch.  The
+RAILS_RELATIVE_URL_ROOT is set by the aforementioned \--path switch.
+Either of these variables may also be set in the shell or the Unicorn
+CONFIG_FILE.  All application or library-specific environment variables
+(e.g. TMPDIR, RAILS_ASSET_ID) may always be set in the Unicorn
+CONFIG_FILE in addition to the spawning shell.  When transparently
+upgrading Unicorn, all environment variables set in the old master
+process are inherited by the new master process.  Unicorn only uses (and
+will overwrite) the UNICORN_FD environment variable internally when
+doing transparent upgrades.
+
+# SIGNALS
+
+The following UNIX signals may be sent to the master process:
+
+* HUP - reload config file, app, and gracefully restart all workers
+* INT/TERM - quick shutdown, kills all workers immediately
+* QUIT - graceful shutdown, waits for workers to finish their
+  current request before finishing.
+* USR1 - reopen all logs owned by the master and all workers
+  See Unicorn::Util.reopen_logs for what is considered a log.
+* USR2 - reexecute the running binary.  A separate QUIT
+  should be sent to the original process once the child is verified to
+  be up and running.
+* WINCH - gracefully stops workers but keep the master running.
+  This will only work for daemonized processes.
+* TTIN - increment the number of worker processes by one
+* TTOU - decrement the number of worker processes by one
+
+See the [SIGNALS][4] document for full description of all signals
+used by Unicorn.
+
+# SEE ALSO
+
+* unicorn(1)
+* *Rack::Builder* ri/RDoc
+* *Unicorn::Configurator* ri/RDoc
+* [Unicorn RDoc][1]
+* [Rack RDoc][2]
+* [Rackup HowTo][3]
+
+[1]: http://unicorn.bogomips.org/
+[2]: http://rack.rubyforge.org/doc/
+[3]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
+[4]: http://unicorn.bogomips.org/SIGNALS.html