Browse files

docs: hopefully clarify preload_app=false behavior

While we're at it, inform people of why they might use
a symlink
  • Loading branch information...
1 parent 14da5bd commit f9baab18705218dae4c37c2c92d1ceea151bba8e Eric Wong committed Jun 11, 2010
Showing with 24 additions and 4 deletions.
  1. +6 −1 SIGNALS
  2. +18 −3 lib/unicorn/configurator.rb
@@ -14,7 +14,12 @@ Unicorn and nginx.
will also pick up any application code changes when restarted. If
"preload_app" is true, then application code changes will have no
effect; USR2 + QUIT (see below) must be used to load newer code in
- this case.
+ this case. When reloading the application, +Gem.refresh+ will
+ be called so updated code for your application can pick up newly
+ installed RubyGems. It is not recommended that you uninstall
+ libraries your application depends on while Unicorn is running,
+ as respawned workers may enter a spawn loop when they fail to
+ load an uninstalled dependency.
* INT/TERM - quick shutdown, kills all workers immediately
@@ -311,7 +311,22 @@ def pid(path); set_path(:pid, path); end
# In addition to reloading the unicorn-specific config settings,
# SIGHUP will reload application code in the working
- # directory/symlink when workers are gracefully restarted.
+ # directory/symlink when workers are gracefully restarted when
+ # preload_app=false (the default). As reloading the application
+ # sometimes requires RubyGems updates, +Gem.refresh+ is always
+ # called before the application is loaded (for RubyGems users).
+ #
+ # During deployments, care should _always_ be taken to ensure your
+ # applications are properly deployed and running. Using
+ # preload_app=false (the default) means you _must_ check if
+ # your application is responding properly after a deployment.
+ # Improperly deployed applications can go into a spawn loop
+ # if the application fails to load. While your children are
+ # in a spawn loop, it is is possible to fix an application
+ # by properly deploying all required code and dependencies.
+ # Using preload_app=true means any application load error will
+ # cause the master process to exit with an error.
def preload_app(bool)
case bool
when TrueClass, FalseClass
@@ -344,9 +359,9 @@ def stdout_path(path)
set_path(:stdout_path, path)
- # sets the working directory for Unicorn. This ensures USR2 will
+ # sets the working directory for Unicorn. This ensures SIGUSR2 will
# start a new instance of Unicorn in this directory. This may be
- # a symlink.
+ # a symlink, a common scenario for Capistrano users.
def working_directory(path)
# just let chdir raise errors
path = File.expand_path(path)

0 comments on commit f9baab1

Please sign in to comment.