SIGNALS

   1 == Signal handling
   2
   3 In general, signals need only be sent to the master process.  However,
   4 the signals Rainbows! uses internally to communicate with the worker
   5 processes are documented here as well.  With the exception of TTIN/TTOU,
   6 signal handling matches the behavior of and {nginx}[http://nginx.net/]
   7 so it should be possible to easily share process management scripts
   8 between \Rainbows!, unicorn and nginx.
   9
  10 === Master Process
  11
  12 * HUP - reload config file, app, and gracefully restart all workers
  13   If the "preload_app" directive is false (the default), then workers
  14   will also pick up any application code changes when restarted.  If
  15   "preload_app" is true, then application code changes will have no
  16   effect; USR2 + QUIT (see below) must be used to load newer code in
  17   this case.  When reloading the application, +Gem.refresh+ will
  18   be called so updated code for your application can pick up newly
  19   installed RubyGems.  It is not recommended that you uninstall
  20   libraries your application depends on while Rainbows! is running,
  21   as respawned workers may enter a spawn loop when they fail to
  22   load an uninstalled dependency.
  23
  24 * INT/TERM - quick shutdown, kills all workers immediately
  25
  26 * QUIT - graceful shutdown, waits for workers to finish their
  27   current request before finishing.  Since Rainbows 5.1.0 (Jan 2017),
  28   this waits requests deferred to a separate thread with
  29   EventMachine (app.deferred?(env) => true).
  30
  31 * USR1 - reopen all logs owned by the master and all workers
  32   See Unicorn::Util.reopen_logs for what is considered a log.
  33
  34 * USR2 - reexecute the running binary.  A separate QUIT
  35   should be sent to the original process once the child is verified to
  36   be up and running.
  37
  38 * WINCH - gracefully stops workers but keep the master running.
  39   This will only work for daemonized processes.
  40
  41 * TTIN - increment the number of worker processes by one
  42
  43 * TTOU - decrement the number of worker processes by one
  44
  45 === Worker Processes
  46
  47 Sending signals directly to the worker processes should not normally be
  48 needed.  If the master process is running, any exited worker will be
  49 automatically respawned.
  50
  51 * INT/TERM - Quick shutdown, immediately exit.
  52   Unless WINCH has been sent to the master (or the master is killed),
  53   the master process will respawn a worker to replace this one.
  54
  55 * QUIT - Gracefully exit after finishing the current request.
  56   Unless WINCH has been sent to the master (or the master is killed),
  57   the master process will respawn a worker to replace this one.
  58   This currently does not wait for requests deferred to a separate
  59   thread when using EventMachine (when app.deferred?(env) => true)
  60
  61 * USR1 - Reopen all logs owned by the worker process.
  62   See Unicorn::Util.reopen_logs for what is considered a log.
  63   Unlike unicorn, log files are reopened immediately in \Rainbows!
  64   since worker processes are likely to be serving multiple clients
  65   simutaneously, we can't wait for all of them to finish.
  66
  67 === Procedure to replace a running rainbows executable
  68
  69 You may replace a running instance of rainbows with a new one without
  70 losing any incoming connections.  Doing so will reload all of your
  71 application code, unicorn/Rainbows! config, Ruby executable, and all
  72 libraries.  The only things that will not change (due to OS limitations)
  73 are:
  74
  75 1. The path to the rainbows executable script.  If you want to change to
  76    a different installation of Ruby, you can modify the shebang
  77    line to point to your alternative interpreter.
  78
  79 The procedure is exactly like that of nginx:
  80
  81 1. Send USR2 to the master process
  82
  83 2. Check your process manager or pid files to see if a new master spawned
  84    successfully.  If you're using a pid file, the old process will have
  85    ".oldbin" appended to its path.  You should have two master instances
  86    of rainbows running now, both of which will have workers servicing
  87    requests.  Your process tree should look something like this:
  88
  89      rainbows master (old)
  90      \_ rainbows worker[0]
  91      \_ rainbows worker[1]
  92      \_ rainbows worker[2]
  93      \_ rainbows worker[3]
  94      \_ rainbows master
  95         \_ rainbows worker[0]
  96         \_ rainbows worker[1]
  97         \_ rainbows worker[2]
  98         \_ rainbows worker[3]
  99
 100 3. You can now send WINCH to the old master process so only the new workers
 101    serve requests.  If your rainbows process is bound to an
 102    interactive terminal, you can skip this step.  Step 5 will be more
 103    difficult but you can also skip it if your process is not daemonized.
 104
 105 4. You should now ensure that everything is running correctly with the
 106    new workers as the old workers die off.
 107
 108 5. If everything seems ok, then send QUIT to the old master.  You're done!
 109
 110    If something is broken, then send HUP to the old master to reload
 111    the config and restart its workers.  Then send QUIT to the new master
 112    process.