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

clear(signal = nil) click to toggle source

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
known?(signal) click to toggle source

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
on(signal, &block) click to toggle source

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
on_failure(&block) click to toggle source

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
on_success(&block) click to toggle source

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
trap() click to toggle source

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

run(signal) click to toggle source

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
signal_number(signal, raise_if_unknown = true) click to toggle source

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
signals() click to toggle source

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