The unix signal is a method of sending messages between processes). When a signal is sent, the operating system interrupts the target process’s normal flow of execution. There are standard signals that are used to stop a process but there are also custom signals that can be used for other purposes. This document is an attempt to list all supported signals that Puma will respond to. In general, signals need only be sent to the master process of a cluster.

Sending Signals

If you are new to signals it can be useful to see how they can be used. When a process is created in a *nix like operating system it will have a PID - or process identifier that can be used to send signals to the process. For demonstration we will create an infinitely running process by tailing a file:

  1. $ echo "foo" >> my.log
  2. $ irb
  3. > pid = Process.spawn 'tail -f my.log'

From here we can see that the tail process is running by using the ps command:

  1. $ ps aux | grep tail
  2. schneems        87152   0.0  0.0  2432772    492 s032  S+   12:46PM   0:00.00 tail -f my.log

You can send a signal in Ruby using the Process module:

  1. $ irb
  2. > puts pid
  3. => 87152
  4. Process.detach(pid) # http://ruby-doc.org/core-2.1.1/Process.html#method-c-detach
  5. Process.kill("TERM", pid)

Now you will see via ps that there is no more tail process. Sometimes when referring to signals the SIG prefix will be used for instance SIGTERM is equivalent to sending TERM via Process.kill.

Puma Signals

Puma cluster responds to these signals:

  • TTIN increment the worker count by 1
  • TTOU decrement the worker count by 1
  • TERM send TERM to worker. Worker will attempt to finish then exit.
  • USR2 restart workers. This also reloads puma configuration file, if there is one.
  • USR1 restart workers in phases, a rolling restart. This will not reload configuration file.
  • HUP reopen log files defined in stdout_redirect configuration parameter. If there is no stdout_redirect option provided it will behave like INT
  • INT equivalent of sending Ctrl-C to cluster. Will attempt to finish then exit.
  • CHLD

Callbacks order in case of different signals

Start application

  1. puma configuration file reloaded, if there is one
  2. * Pruning Bundler environment
  3. puma configuration file reloaded, if there is one
  5. before_fork
  6. on_worker_fork
  7. after_worker_fork
  9. Gemfile in context
  11. on_worker_boot
  13. Code of the app is loaded and running

Send USR2

  1. on_worker_shutdown
  2. on_restart
  4. puma configuration file reloaded, if there is one
  6. before_fork
  7. on_worker_fork
  8. after_worker_fork
  10. Gemfile in context
  12. on_worker_boot
  14. Code of the app is loaded and running

Send USR1

  1. on_worker_shutdown
  2. on_worker_fork
  3. after_worker_fork
  5. Gemfile in context
  7. on_worker_boot
  9. Code of the app is loaded and running