README

   1 = Unicorn: UNIX + LAN/localhost-only fork of Mongrel
   2
   3 Only run this behind a full-HTTP-request-buffering reverse proxy if
   4 you're serving slow clients.  That said, nginx is the only reverse
   5 proxy we know of that meets this requirement.
   6
   7 == Features
   8
   9  * process management: Unicorn will reap and restart workers that
  10    die because of broken apps and there is no need to manage
  11    multiple processes yourself.
  12
  13  * doesn't matter if your application is thread-safe or not, workers
  14    all run within their own isolated address space and only serve one
  15    client at a time...
  16
  17  * able to listen on multiple interfaces, including UNIX sockets,
  18    each worker process can also bind to a private port via the
  19    after_fork hook for easy debugging.
  20
  21  * should support all Rack applications (though only Sinatra has been tested)
  22
  23  * nginx-style binary re-execution without losing connections.
  24    You can upgrade unicorn, your entire application, libraries
  25    and even your Ruby interpreter as long as unicorn is
  26    installed in the same path
  27
  28  * before_fork and after_fork hooks in case your application
  29    has special needs when dealing with forked processes.  These
  30    can be used to setup signal handlers for logrotation, too.
  31
  32  * Ruby 1.9-compatible (at least the test cases all pass :>)
  33
  34 == Design
  35
  36  * Simplicity: Unicorn is a traditional UNIX prefork web server.
  37    No threads are used at all, this makes applications easier to debug
  38    and fix.  When your application goes awry, a BOFH can just
  39    "kill -9" the runaway worker process without worrying about tearing
  40    all clients down, just one.  Only UNIX-like systems supporting
  41    fork() and file descriptor inheritance is supported.
  42
  43  * The Ragel->C HTTP parser is taken from Mongrel.  This is the
  44    only non-Ruby part and there are no plans to add any more
  45    non-Ruby components.
  46
  47  * All HTTP protocol parsing and I/O is done just like Mongrel:
  48    1. read/parse HTTP request in full
  49    2. call Rack application
  50    3. write HTTP response back to the client
  51
  52  * Like Mongrel, neither keepalive nor pipelining are supported.
  53    These aren't needed since Unicorn is only designed to serve
  54    fast, low-latency clients directly.  Do one thing, do it well;
  55    let nginx handle slow clients.
  56
  57  * Configuration is purely in Ruby and eval().  Ruby is less
  58    ambiguous than YAML and lets lambdas for
  59    before_fork/after_fork/before_exec hooks be defined inline.  An
  60    optional, separate config_file may be used to modify supported
  61    configuration changes (and also gives you plenty of rope if you RTFS
  62    :>)
  63
  64  * One master process spawns and reaps worker processes.  The
  65    Rack application itself is called only within the worker process (but
  66    can be loaded within the master).  A copy-on-write friendly garbage
  67    collector like Ruby Enterprise Edition can be used to minimize memory
  68    usage along with the "preload_app true" directive.
  69
  70  * The number of worker processes should be scaled to the number of
  71    CPUs, memory or even spindles you have.  If you have an existing
  72    Mongrel cluster, using the same amount of processes should work.
  73    Let a full-HTTP-request-buffering reverse proxy like nginx manage
  74    concurrency to thousands of slow clients for you.  Unicorn scaling
  75    should only be concerned about limits of your backend system(s).
  76
  77  * Load balancing between worker processes is done by the OS kernel.
  78    All workers share a common set of listener sockets and does
  79    non-blocking accept() on them.  The kernel will decide which worker
  80    process to give a socket to and workers will sleep if there is
  81    nothing to accept().
  82
  83  * Since non-blocking accept() is used, there can be a thundering
  84    herd when an occasional client connects when application
  85    *is not busy*.  The thundering herd problem should not affect
  86    applications that are running all the time since worker processes
  87    will only select()/accept() outside of the application dispatch.
  88
  89  * Blocking I/O is used for clients.  This allows a simpler code path
  90    to be followed within the Ruby interpreter and fewer syscalls.
  91    Applications that use threads should continue to work if Unicorn
  92    is serving LAN or localhost clients.
  93
  94  * Timeout implementation is done via fchmod(2) in each worker
  95    on a shared file descriptor to update st_ctime on the inode.
  96    Master process wakeups for checking on timeouts is throttled
  97    one a second to minimize the performance impact and simplify
  98    the code path within the worker.  Neither futimes(2) nor
  99    pwrite(2)/pread(2) are supported by base MRI, nor are they as
 100    portable on UNIX systems as fchmod(2).
 101
 102  * SIGKILL is used to terminate the timed-out workers as reliably
 103    as possible on a UNIX system.
 104
 105  * The poor performance of select() on large FD sets is avoided
 106    as few file descriptors are used in each worker.
 107    There should be no gain from moving to highly scalable but
 108    unportable event notification solutions for watching few
 109    file descriptors.
 110
 111  * If the master process dies unexpectedly for any reason,
 112    workers will notice within :timeout/2 seconds and follow
 113    the master to its death.
 114
 115 == License
 116
 117 Unicorn is copyright 2009 Eric Wong and contributors.
 118 It is based on Mongrel:
 119
 120 Mongrel is copyright 2007 Zed A. Shaw and contributors. It is licensed
 121 under the Ruby license and the GPL2. See the include LICENSE file for
 122 details.
 123
 124 == Install
 125
 126 The library consists of a C extension so you'll need a C compiler or at
 127 least a friend who can build it for you.
 128
 129 Finally, the source includes a setup.rb for those who hate RubyGems.
 130
 131 You can get the source via git via the following locations:
 132
 133   git://git.bogomips.org/unicorn.git
 134
 135   http://git.bogomips.org/unicorn.git
 136
 137 == Usage
 138
 139 Unicorn will look for the config.ru file used by rackup in APP_ROOT.
 140 Optionally, it can use a config file specified by the --config-file/-c
 141 command-line switch.
 142
 143 Unicorn should be capable of running all Rack applications.  Since this
 144 is a preforking webserver, you do not have to worry about thread-safety
 145 of your application or libraries. However, your Rack application may use
 146 threads internally (and should even be able to continue running threads
 147 after the request is complete).
 148
 149 == Contact
 150
 151 Newsgroup and mailing list coming, or it'll be a part of the Mongrel project...
 152
 153 Email Eric Wong at normalperson@yhbt.net for now.