module Upoj::Signals
Register of blocks of code to execute when the script receives a particular signal.
Constants
- FAILURE_STATUSES
List of exit statuses considered a termination. 2 = INT, 3 = QUIT, 9 = KILL, 15 = TERM
- SUCCESS_STATUSES
List of exit statuses considered successful. 0 = EXIT
Public Class Methods
Clears all blocks registered for the given signal. Use nil to clear all blocks for all signals.
No error will be raised if the signal is unknown.
# File lib/upoj-rb/signals.rb, line 21 def self.clear signal = nil signal ? @@trapped[signal_number(signal, false)].try(:clear) : @@trapped.clear; nil end
Indicates whether the given signal is valid, i.e. whether it is either a number or one of the text signals returned by Signal#list.
# File lib/upoj-rb/signals.rb, line 84 def self.known? signal !!signal_number(signal, false) end
Registers a block to be executed when the script receives a given signal. This method can be called several times; all registered blocks will be called in the order they were registered when the signal is received. If the signal is not known, ArgumentError is raised (see known?).
Signals.trap
must be called after registering the blocks for them to be activated.
Arguments¶ ↑
-
signal
- The signal to trap. -
&block
- The block to execute when the signal is trapped.
Examples¶ ↑
Upoj::CLI::Signals.on(:exit){ cleanup_temporary_files } Upoj::CLI::Signals.on("TERM"){ close_connections } Upoj::CLI::Signals.on(2) do puts usage end
# File lib/upoj-rb/signals.rb, line 44 def self.on signal, &block (@@trapped[signal_number(signal)] ||= []) << block; block end
Blocks registered with this method will be executed if the script exits with any of the following statuses: QUIT, TERM, KILL, INT
(2, 3, 9, 15).
Signals.trap
must be called after registering the blocks for them to be activated.
Arguments¶ ↑
-
&block
- The block to execute when the script fails.
Examples¶ ↑
Upoj::CLI::Signals.on_failure{ close_connections }
# File lib/upoj-rb/signals.rb, line 61 def self.on_failure &block FAILURE_STATUSES.each{ |status| self.on status, &block }; block end
Blocks registered with this method will be executed if the script exits successfully with status EXIT
(0).
Signals.trap
must be called after registering the blocks for them to be activated.
Arguments¶ ↑
-
&block
- The block to execute when the script exits successfully.
Examples¶ ↑
Upoj::CLI::Signals.on_success{ FileUtils.rm_fr tmp }
# File lib/upoj-rb/signals.rb, line 77 def self.on_success &block SUCCESS_STATUSES.each{ |status| self.on status, &block }; block end
Traps script signals. Blocks registered with Signals.on
will be executed when the script receives the corresponding status.
Blocks previously trapped without using this class will be replaced.
Returns true if any signals were trapped.
# File lib/upoj-rb/signals.rb, line 12 def self.trap @@trapped.each_key{ |signal| Signal.trap(signal){ self.run signal } } @@trapped.any? end
Private Class Methods
Runs all the blocks registered for the given signal.
# File lib/upoj-rb/signals.rb, line 105 def self.run signal @@trapped[signal].try(:each){ |block| block.try :call, signal } end
Returns the numerical value of the given signal. Statuses in Signal#list can be given as text.
# File lib/upoj-rb/signals.rb, line 98 def self.signal_number signal, raise_if_unknown = true (signal.kind_of?(Fixnum) ? signal : signals[signal.to_s.upcase]).tap do |n| raise ArgumentError, "Unknown signal '#{signal}'. Signal must either be a number or one of the text signals returned by Signal.list." if raise_if_unknown && !n end end
Returns the map of signal names and their numerical value returned by Signal#list.
# File lib/upoj-rb/signals.rb, line 92 def self.signals @@signals ||= Signal.list end