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 before_fork/after_fork
  59    hooks be defined inline.  An optional, separate hot_config_file
  60    may be used to modify supported configuration changes
  61    (and also gives you plenty of rope if you RTFS :>)
  62
  63  * One master process spawns and reaps worker processes.  The
  64    Rack application itself is called only within the worker process (but
  65    can be loaded within the master).  A copy-on-write friendly garbage
  66    collector like Ruby Enterprise Edition can be used to minimize memory
  67    usage.
  68
  69  * The number of worker processes should be scaled to the number of
  70    CPUs, memory or even spindles you have.  If you have an existing
  71    Mongrel cluster, using the same amount of processes should work.
  72    Let a full-HTTP-request-buffering reverse proxy like nginx manage
  73    concurrency to thousands of slow clients for you.  Unicorn scaling
  74    should only be concerned about limits of your backend system(s).
  75
  76  * Load balancing between worker processes is done by the OS kernel.
  77    All workers share a common set of listener sockets and does
  78    non-blocking accept() on them.  The kernel will decide which worker
  79    process to give a socket to and workers will sleep if there is
  80    nothing to accept().
  81
  82  * Since non-blocking accept() is used, there can be a thundering
  83    herd when an occasional client connects when application
  84    *is not busy*.  The thundering herd problem should not affect
  85    applications that are running all the time since worker processes
  86    will only select()/accept() outside of the application dispatch.
  87
  88  * Blocking I/O is used for clients.  This allows a simpler code path
  89    to be followed within the Ruby interpreter and fewer syscalls.
  90    Applications that use threads should continue to work if Unicorn
  91    is serving LAN or localhost clients.
  92
  93  * Timeout implementation is done via fchmod(2) in each worker
  94    on a shared file descriptor to update st_ctime on the inode.
  95    Master process wakeups for checking on timeouts is throttled
  96    one a second to minimize the performance impact and simplify
  97    the code path within the worker.  Neither futimes(2) nor
  98    pwrite(2)/pread(2) are supported by base MRI, nor are they as
  99    portable on UNIX systems as fchmod(2).
 100
 101  * SIGKILL is used to terminate the timed-out workers as reliably
 102    as possible on a UNIX system.
 103
 104  * The poor performance of select() on large FD sets is avoided
 105    as few file descriptors are used in each worker.
 106    There should be no gain from moving to highly scalable but
 107    unportable event notification solutions for watching few
 108    file descriptors.
 109
 110  * If the master process dies unexpectedly for any reason,
 111    workers will notice within :timeout/2 seconds and follow
 112    the master to its death.
 113
 114 == License
 115
 116 Unicorn is copyright 2009 Eric Wong and contributors.
 117 It is based on Mongrel:
 118
 119 Mongrel is copyright 2007 Zed A. Shaw and contributors. It is licensed
 120 under the Ruby license and the GPL2. See the include LICENSE file for
 121 details.
 122
 123 == Install
 124
 125 The library consists of a C extension so you'll need a C compiler or at
 126 least a friend who can build it for you.
 127
 128 Finally, the source includes a setup.rb for those who hate RubyGems.
 129
 130 You can get the source via git via the following locations:
 131
 132   git://git.bogomips.org/unicorn.git
 133
 134   http://git.bogomips.org/unicorn.git
 135
 136 == Usage
 137
 138 See the Sinatra example.
 139
 140 It should be capable of running all Rack applications.  Since this is a
 141 preforking webserver, you do not have to worry about thread-safety of your
 142 application or libraries. However, your Rack application may use threads
 143 internally (and should even be able to continue running threads after the
 144 request is complete).
 145
 146 == Contact
 147
 148 Newsgroup and mailing list coming, or it'll be a part of the Mongrel project...
 149
 150 Email Eric Wong at normalperson@yhbt.net for now.