DESIGN

   1 == Design
   2
   3 * Simplicity: Unicorn is a traditional UNIX prefork web server.
   4   No threads are used at all, this makes applications easier to debug
   5   and fix.  When your application goes awry, a BOFH can just
   6   "kill -9" the runaway worker process without worrying about tearing
   7   all clients down, just one.  Only UNIX-like systems supporting
   8   fork() and file descriptor inheritance are supported.
   9
  10 * The Ragel->C HTTP parser is taken from Mongrel.  This is the
  11   only non-Ruby part and there are no plans to add any more
  12   non-Ruby components.
  13
  14 * All HTTP protocol parsing and I/O is done just like Mongrel:
  15     1. read/parse HTTP request in full
  16     2. call Rack application
  17     3. write HTTP response back to the client
  18
  19 * Like Mongrel, neither keepalive nor pipelining are supported.
  20   These aren't needed since Unicorn is only designed to serve
  21   fast, low-latency clients directly.  Do one thing, do it well;
  22   let nginx handle slow clients.
  23
  24 * Configuration is purely in Ruby and eval().  Ruby is less
  25   ambiguous than YAML and lets lambdas for
  26   before_fork/after_fork/before_exec hooks be defined inline.  An
  27   optional, separate config_file may be used to modify supported
  28   configuration changes (and also gives you plenty of rope if you RTFS
  29   :>)
  30
  31 * One master process spawns and reaps worker processes.  The
  32   Rack application itself is called only within the worker process (but
  33   can be loaded within the master).  A copy-on-write friendly garbage
  34   collector like Ruby Enterprise Edition can be used to minimize memory
  35   usage along with the "preload_app true" directive (see
  36   Unicorn::Configurator).
  37
  38 * The number of worker processes should be scaled to the number of
  39   CPUs, memory or even spindles you have.  If you have an existing
  40   Mongrel cluster on a single-threaded app, using the same amount of
  41   processes should work.  Let a full-HTTP-request-buffering reverse
  42   proxy like nginx manage concurrency to thousands of slow clients for
  43   you.  Unicorn scaling should only be concerned about limits of your
  44   backend system(s).
  45
  46 * Load balancing between worker processes is done by the OS kernel.
  47   All workers share a common set of listener sockets and does
  48   non-blocking accept() on them.  The kernel will decide which worker
  49   process to give a socket to and workers will sleep if there is
  50   nothing to accept().
  51
  52 * Since non-blocking accept() is used, there can be a thundering
  53   herd when an occasional client connects when application
  54   *is not busy*.  The thundering herd problem should not affect
  55   applications that are running all the time since worker processes
  56   will only select()/accept() outside of the application dispatch.
  57
  58 * Blocking I/O is used for clients.  This allows a simpler code path
  59   to be followed within the Ruby interpreter and fewer syscalls.
  60   Applications that use threads continue to work if Unicorn
  61   is only serving LAN or localhost clients.
  62
  63 * Timeout implementation is done via fchmod(2) in each worker
  64   on a shared file descriptor to update st_ctime on the inode.
  65   Master process wakeups for checking on timeouts is throttled
  66   one a second to minimize the performance impact and simplify
  67   the code path within the worker.  Neither futimes(2) nor
  68   pwrite(2)/pread(2) are supported by base MRI, nor are they as
  69   portable on UNIX systems as fchmod(2).
  70
  71 * SIGKILL is used to terminate the timed-out workers from misbehaving apps
  72   as reliably as possible on a UNIX system.  The default timeout is a
  73   generous 60 seconds (same default as in Mongrel).
  74
  75 * The poor performance of select() on large FD sets is avoided
  76   as few file descriptors are used in each worker.
  77   There should be no gain from moving to highly scalable but
  78   unportable event notification solutions for watching few
  79   file descriptors.
  80
  81 * If the master process dies unexpectedly for any reason,
  82   workers will notice within :timeout/2 seconds and follow
  83   the master to its death.
  84
  85 * There is never any explicit real-time dependency or communication
  86   between the worker processes nor to the master process.
  87   Synchronization is handled entirely by the OS kernel and shared
  88   resources are never accessed by the worker when it is servicing
  89   a client.