3 Occasionally odd {issues}[link:ISSUES.html] arise without a transparent or
4 acceptable solution. Those issues are documented here.
6 * Under Ruby 1.9.1, methods like Array#shuffle and Array#sample will
7 segfault if called after forking. This is fixed in trunk (r26936) and
8 should be backported to the next 1.9.1 stable release (after p378).
9 Until then, it is advisable to call "Kernel.rand" in your after_fork
10 hook to reinitialize the random number generator.
12 See http://redmine.ruby-lang.org/issues/show/2962 for more details
14 * When using "preload_app true", with apps using background threads
15 need to restart them in the after_fork hook because threads are never
16 shared with child processes. Additionally, any synchronization
17 primitives (Mutexes, Monitors, ConditionVariables) should be
18 reinitialized in case they are held during fork time to avoid
19 deadlocks. The core Ruby Logger class needlessly uses a MonitorMutex
20 which can be disabled with a {monkey patch}[link:examples/logger_mp_safe.rb]
22 * Rails 2.3.2 bundles its own version of Rack. This may cause subtle
23 bugs when simultaneously loaded with the system-wide Rack Rubygem
24 which Unicorn depends on. Upgrading to Rails 2.3.4 (or later) is
25 strongly recommended for all Rails 2.3.x users for this (and security
26 reasons). Rails 2.2.x series (or before) did not bundle Rack and are
27 should be unnaffected. If there is any reason which forces your
28 application to use Rails 2.3.2 and you have no other choice, then
29 you may edit your Unicorn gemspec and remove the Rack dependency.
31 ref: http://mid.gmane.org/20091014221552.GA30624@dcvr.yhbt.net
32 Note: the workaround described in the article above only made
33 the issue more subtle and we didn't notice them immediately.
35 * Installing "unicorn" as a system-wide Rubygem and using the
36 {isolate}[http://github.com/jbarnette/isolate] gem may cause issues if
37 you're using any of the bundled application-level libraries in
38 unicorn/app/* (for compatibility with CGI-based applications, Rails <=
39 2.2.2, or ExecCgi). For now workarounds include:
41 * installing the same version of unicorn as a system-wide Rubygem
42 _and_ isolating unicorn as well.
43 * explicitly setting RUBYLIB or $LOAD_PATH to include any gem path
44 where the unicorn gem is installed (e.g.
45 /usr/lib/ruby/gems/1.8/gems/unicorn-VERSION/lib)
47 With current versions of isolate, it is also recommended that you
48 disable it with the <tt>before_exec</tt> hook prevent the PATH and
49 RUBYOPT environment variable modifications from propagating between
50 upgrades in your Unicorn config file:
52 before_exec do |server|
56 Future versions (unreleased as of 2010.04.20) of isolate will not
57 require this as environment variable modifications will be idempotent.
59 * WONTFIX: code reloading and restarts with Sinatra 0.3.x (and likely older
60 versions) apps is broken. The workaround is to force production
61 mode to disable code reloading as well as disabling "run" in your
65 Since this is no longer an issue with Sinatra 0.9.x apps, this will not be
66 fixed on our end. Since Unicorn is itself the application launcher, the
67 at_exit handler used in old Sinatra always caused Mongrel to be launched
68 whenever a Unicorn worker was about to exit.
70 Also remember we're capable of replacing the running binary without dropping
71 any connections regardless of framework :)