# enum Signal

##
Overview

Safely handle inter-process signals on POSIX systems.

Signals are dispatched to the event loop and later processed in a dedicated fiber. Some received signals may never be processed when the program terminates.

    puts "Ctrl+C still has the OS default action (stops the program)"
    sleep 3.seconds

    Signal::INT.trap do
      puts "Gotcha!"
    end
    puts "Ctrl+C will be caught from now on"
    sleep 3.seconds

    Signal::INT.reset
    puts "Ctrl+C is back to the OS default action"
    sleep 3.seconds

WARNING An uncaught exception in a signal handler is a fatal error.

##
Portability

The set of available signals is platform-dependent. Only signals that exist on the target platform are available as members of this enum.

- `ABRT`, `FPE`, `ILL`, `INT`, `SEGV`, and `TERM` are guaranteed to exist on all platforms.
- `PWR`, `STKFLT`, and `UNUSED` only exist on Linux.
- `BREAK` only exists on Windows.
- All other signals exist on all POSIX platforms.

The methods `#trap`, `#reset`, and `#ignore` may not be implemented at all on non-POSIX systems.

The standard library provides several platform-agnostic APIs to achieve tasks that are typically solved with signals on POSIX systems:

- The portable API for responding to a termination request is `Process.on_terminate`.
- The portable API for sending a `TERM` or `KILL` signal to a process is `Process#terminate`.
- The portable API for retrieving the exit signal of a process (`Process::Status#exit_signal`) is `Process::Status#exit_reason`.

##
Defined in:

signal.cr

##
Enum Members

INT = `2`
ILL = `4`
FPE = `8`
SEGV = `11`
TERM = `15`
ABRT = `6`
HUP = `1`
QUIT = `3`
TRAP = `5`
IOT = `6`
KILL = `9`
BUS = `7`
SYS = `31`
PIPE = `13`
ALRM = `14`
URG = `23`
STOP = `19`
TSTP = `20`
CONT = `18`
CHLD = `17`
TTIN = `21`
TTOU = `22`
IO = `29`
XCPU = `24`
XFSZ = `25`
VTALRM = `26`
USR1 = `10`
USR2 = `12`
WINCH = `28`
PWR = `30`
STKFLT = `16`
UNUSED = `31`

##
Instance Method Summary

- #abrt?

  Returns `true` if this enum value equals `ABRT`

- #alrm?

  Returns `true` if this enum value equals `ALRM`

- #bus?

  Returns `true` if this enum value equals `BUS`

- #chld?

  Returns `true` if this enum value equals `CHLD`

- #cont?

  Returns `true` if this enum value equals `CONT`

- #fpe?

  Returns `true` if this enum value equals `FPE`

- #hup?

  Returns `true` if this enum value equals `HUP`

- #ignore : Nil

  Clears the handler for this signal and prevents the OS default action.

- #ill?

  Returns `true` if this enum value equals `ILL`

- #int?

  Returns `true` if this enum value equals `INT`

- #io?

  Returns `true` if this enum value equals `IO`

- #iot?

  Returns `true` if this enum value equals `IOT`

- #kill?

  Returns `true` if this enum value equals `KILL`

- #pipe?

  Returns `true` if this enum value equals `PIPE`

- #pwr?

  Returns `true` if this enum value equals `PWR`

- #quit?

  Returns `true` if this enum value equals `QUIT`

- #reset : Nil

  Resets the handler for this signal to the OS default.

- #segv?

  Returns `true` if this enum value equals `SEGV`

- #stkflt?

  Returns `true` if this enum value equals `STKFLT`

- #stop?

  Returns `true` if this enum value equals `STOP`

- #sys?

  Returns `true` if this enum value equals `SYS`

- #term?

  Returns `true` if this enum value equals `TERM`

- #trap(&handler : Signal -> ) : Nil

  Sets the handler for this signal to the passed function.

- #trap?

  Returns `true` if this enum value equals `TRAP`

- #trap_handler?

  Returns any existing handler for this signal

- #tstp?

  Returns `true` if this enum value equals `TSTP`

- #ttin?

  Returns `true` if this enum value equals `TTIN`

- #ttou?

  Returns `true` if this enum value equals `TTOU`

- #unused?

  Returns `true` if this enum value equals `UNUSED`

- #urg?

  Returns `true` if this enum value equals `URG`

- #usr1?

  Returns `true` if this enum value equals `USR1`

- #usr2?

  Returns `true` if this enum value equals `USR2`

- #vtalrm?

  Returns `true` if this enum value equals `VTALRM`

- #winch?

  Returns `true` if this enum value equals `WINCH`

- #xcpu?

  Returns `true` if this enum value equals `XCPU`

- #xfsz?

  Returns `true` if this enum value equals `XFSZ`

### Instance methods inherited from struct `Enum`

&(other : self) : self &, +(other : Int) : self +, -(other : Int) : self -, <=>(other : self) <=>, ==(other : self)
==(other) ==, ^(other : self) : self ^, |(other : self) : self |, ~ : self ~, clone clone, each(& : self -> ) each, hash(hasher) hash, includes?(other : self) : Bool includes?, inspect(io : IO) : Nil inspect, to_f32 : Float32 to_f32, to_f32! : Float32 to_f32!, to_f64 : Float64 to_f64, to_f64! : Float64 to_f64!, to_i : Int32 to_i, to_i128 : Int128 to_i128, to_i128! : Int128 to_i128!, to_i16 : Int16 to_i16, to_i16! : Int16 to_i16!, to_i32 : Int32 to_i32, to_i32! : Int32 to_i32!, to_i64 : Int64 to_i64, to_i64! : Int64 to_i64!, to_i8 : Int8 to_i8, to_i8! : Int8 to_i8!, to_json(json : JSON::Builder) : Nil to_json, to_s(io : IO) : Nil
to_s : String to_s, to_u128 : UInt128 to_u128, to_u128! : UInt128 to_u128!, to_u16 : UInt16 to_u16, to_u16! : UInt16 to_u16!, to_u32 : UInt32 to_u32, to_u32! : UInt32 to_u32!, to_u64 : UInt64 to_u64, to_u64! : UInt64 to_u64!, to_u8 : UInt8 to_u8, to_u8! : UInt8 to_u8!, to_yaml(yaml : YAML::Nodes::Builder) to_yaml, value : Int value

### Constructor methods inherited from struct `Enum`

from_value(value : Int) : self from_value, new(ctx : YAML::ParseContext, node : YAML::Nodes::Node)
new(value : self)
new(pull : JSON::PullParser) : self new, parse(string : String) : self parse

### Class methods inherited from struct `Enum`

each(& : self -> ) each, from_value?(value : Int) : self | Nil from_value?, names : Array(String) names, parse?(string : String) : self | Nil parse?, valid?(value : self) : Bool valid?, values : Array(self) values

### Macros inherited from struct `Enum`

[](*values) [], flags(*values) flags

### Instance methods inherited from module `Comparable(Enum)`

<(other : T) : Bool <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) : Bool >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from struct `Value`

==(other : Log::Metadata::Value)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io : String | IO, root : String)
from_json(string_or_io : String | IO) from_json, from_yaml(string_or_io : String | IO) from_yaml

### Macros inherited from class `Object`

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

##
Instance Method Detail

def abrt? #

Returns `true` if this enum value equals `ABRT`

def alrm? #

Returns `true` if this enum value equals `ALRM`

def bus? #

Returns `true` if this enum value equals `BUS`

def chld? #

Returns `true` if this enum value equals `CHLD`

def cont? #

Returns `true` if this enum value equals `CONT`

def fpe? #

Returns `true` if this enum value equals `FPE`

def hup? #

Returns `true` if this enum value equals `HUP`

def ignore : Nil #

Clears the handler for this signal and prevents the OS default action.

Note that trying to ignore `CHLD` will actually set the default crystal handler that monitors and reaps child processes. This prevents zombie processes and is required by `Process#wait` for example.

def ill? #

Returns `true` if this enum value equals `ILL`

def int? #

Returns `true` if this enum value equals `INT`

def io? #

Returns `true` if this enum value equals `IO`

def iot? #

Returns `true` if this enum value equals `IOT`

def kill? #

Returns `true` if this enum value equals `KILL`

def pipe? #

Returns `true` if this enum value equals `PIPE`

def pwr? #

Returns `true` if this enum value equals `PWR`

def quit? #

Returns `true` if this enum value equals `QUIT`

def reset : Nil #

Resets the handler for this signal to the OS default.

Note that trying to reset `CHLD` will actually set the default crystal handler that monitors and reaps child processes. This prevents zombie processes and is required by `Process#wait` for example.

def segv? #

Returns `true` if this enum value equals `SEGV`

def stkflt? #

Returns `true` if this enum value equals `STKFLT`

def stop? #

Returns `true` if this enum value equals `STOP`

def sys? #

Returns `true` if this enum value equals `SYS`

def term? #

Returns `true` if this enum value equals `TERM`

def trap(&handler : Signal -> ) : Nil #

Sets the handler for this signal to the passed function.

After executing this, whenever the current process receives the corresponding signal, the passed function will be called (instead of the OS default). The handler will run in a signal-safe fiber throughout the event loop; there is no limit to what functions can be called, unlike raw signals that run on the sigaltstack.

Note that `CHLD` is always trapped and child processes will always be reaped before the custom handler is called, hence a custom `CHLD` handler must check child processes using `Process.exists?`. Trying to use waitpid with a zero or negative value won't work.

NOTE `Process.on_terminate` is preferred over `Signal::INT.trap` as a portable alternative which also works on Windows.

def trap? #

Returns `true` if this enum value equals `TRAP`

def trap_handler? #

Returns any existing handler for this signal

    Signal::USR1.trap { }
    prev_handler = Signal::USR1.trap_handler?

    Signal::USR1.trap do |signal|
      prev_handler.try &.call(signal)
      # ...
    end

def tstp? #

Returns `true` if this enum value equals `TSTP`

def ttin? #

Returns `true` if this enum value equals `TTIN`

def ttou? #

Returns `true` if this enum value equals `TTOU`

def unused? #

Returns `true` if this enum value equals `UNUSED`

def urg? #

Returns `true` if this enum value equals `URG`

def usr1? #

Returns `true` if this enum value equals `USR1`

def usr2? #

Returns `true` if this enum value equals `USR2`

def vtalrm? #

Returns `true` if this enum value equals `VTALRM`

def winch? #

Returns `true` if this enum value equals `WINCH`

def xcpu? #

Returns `true` if this enum value equals `XCPU`

def xfsz? #

Returns `true` if this enum value equals `XFSZ`