1 = Unicorn: UNIX + LAN/localhost-only fork of Mongrel
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.
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.
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
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.
21 * should support all Rack applications (though only Sinatra has been tested)
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
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.
32 * Ruby 1.9-compatible (at least the test cases all pass :>)
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.
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
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
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.
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 :>)
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
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).
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
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.
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.
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).
101 * SIGKILL is used to terminate the timed-out workers as reliably
102 as possible on a UNIX system.
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
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.
116 Unicorn is copyright 2009 Eric Wong and contributors.
117 It is based on Mongrel:
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
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.
128 Finally, the source includes a setup.rb for those who hate RubyGems.
130 You can get the source via git via the following locations:
132 git://git.bogomips.org/unicorn.git
134 http://git.bogomips.org/unicorn.git
138 See the Sinatra example.
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).
148 Newsgroup and mailing list coming, or it'll be a part of the Mongrel project...
150 Email Eric Wong at normalperson@yhbt.net for now.