3 Occasionally odd {issues}[link:ISSUES.html] arise without a transparent or
4 acceptable solution. Those issues are documented here.
6 * When using "preload_app true", with apps using background threads
7 need to restart them in the after_fork hook because threads are never
8 shared with child processes. Additionally, any synchronization
9 primitives (Mutexes, Monitors, ConditionVariables) should be
10 reinitialized in case they are held during fork time to avoid
11 deadlocks. The core Ruby Logger class needlessly uses a MonitorMutex
12 which can be disabled with a {monkey patch}[link:examples/logger_mp_safe.rb]
14 * Rails 2.3.2 bundles its own version of Rack. This may cause subtle
15 bugs when simultaneously loaded with the system-wide Rack Rubygem
16 which Unicorn depends on. Upgrading to Rails 2.3.4 (or later) is
17 strongly recommended for all Rails 2.3.x users for this (and security
18 reasons). Rails 2.2.x series (or before) did not bundle Rack and are
19 should be unnaffected. If there is any reason which forces your
20 application to use Rails 2.3.2 and you have no other choice, then
21 you may edit your Unicorn gemspec and remove the Rack dependency.
23 ref: http://mid.gmane.org/20091014221552.GA30624@dcvr.yhbt.net
24 Note: the workaround described in the article above only made
25 the issue more subtle and we didn't notice them immediately.
27 * Installing "unicorn" as a system-wide Rubygem and using the
28 {isolate}[http://github.com/jbarnette/isolate] gem may cause issues if
29 you're using any of the bundled application-level libraries in
30 unicorn/app/* (for compatibility with CGI-based applications, Rails <=
31 2.2.2, or ExecCgi). For now workarounds include:
33 * installing the same version of unicorn as a system-wide Rubygem
34 _and_ isolating unicorn as well.
35 * explicitly setting RUBYLIB or $LOAD_PATH to include any gem path
36 where the unicorn gem is installed (e.g.
37 /usr/lib/ruby/gems/1.8/gems/unicorn-VERSION/lib)
39 * WONTFIX: code reloading and restarts with Sinatra 0.3.x (and likely older
40 versions) apps is broken. The workaround is to force production
41 mode to disable code reloading as well as disabling "run" in your
45 Since this is no longer an issue with Sinatra 0.9.x apps, this will not be
46 fixed on our end. Since Unicorn is itself the application launcher, the
47 at_exit handler used in old Sinatra always caused Mongrel to be launched
48 whenever a Unicorn worker was about to exit.
50 Also remember we're capable of replacing the running binary without dropping
51 any connections regardless of framework :)