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, andTERM are guaranteed to exist on all platforms.
PWR,STKFLT, andUNUSED 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 aTERM orKILL signal to a process is Process#terminate.
The portable API for retrieving the exit signal of a process (Process::Status#exit_signal) isProcess::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?
Returnstrue if this enum value equalsABRT
#alrm?
Returnstrue if this enum value equalsALRM
#bus?
Returnstrue if this enum value equalsBUS
#chld?
Returnstrue if this enum value equalsCHLD
#cont?
Returnstrue if this enum value equalsCONT
#fpe?
Returnstrue if this enum value equalsFPE
#hup?
Returnstrue if this enum value equalsHUP
#ignore : Nil
Clears the handler for this signal and prevents the OS default action.
#ill?
Returnstrue if this enum value equalsILL
#int?
Returnstrue if this enum value equalsINT
#io?
Returnstrue if this enum value equalsIO
#iot?
Returnstrue if this enum value equalsIOT
#kill?
Returnstrue if this enum value equalsKILL
#pipe?
Returnstrue if this enum value equalsPIPE
#pwr?
Returnstrue if this enum value equalsPWR
#quit?
Returnstrue if this enum value equalsQUIT
#reset : Nil
Resets the handler for this signal to the OS default.
#segv?
Returnstrue if this enum value equalsSEGV
#stkflt?
Returnstrue if this enum value equalsSTKFLT
#stop?
Returnstrue if this enum value equalsSTOP
#sys?
Returnstrue if this enum value equalsSYS
#term?
Returnstrue if this enum value equalsTERM
#trap(&handler : Signal -> ) : Nil
Sets the handler for this signal to the passed function.
#trap?
Returnstrue if this enum value equalsTRAP
#trap_handler?
Returns any existing handler for this signal
#tstp?
Returnstrue if this enum value equalsTSTP
#ttin?
Returnstrue if this enum value equalsTTIN
#ttou?
Returnstrue if this enum value equalsTTOU
#unused?
Returnstrue if this enum value equalsUNUSED
#urg?
Returnstrue if this enum value equalsURG
#usr1?
Returnstrue if this enum value equalsUSR1
#usr2?
Returnstrue if this enum value equalsUSR2
#vtalrm?
Returnstrue if this enum value equalsVTALRM
#winch?
Returnstrue if this enum value equalsWINCH
#xcpu?
Returnstrue if this enum value equalsXCPU
#xfsz?
Returnstrue if this enum value equalsXFSZ

Instance methods inherited from struct `Enum`

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Constructor methods inherited from struct `Enum`

, ,

Class methods inherited from struct `Enum`

, , , , ,

Macros inherited from struct `Enum`

Instance methods inherited from module `Comparable(Enum)`

, , , , , ,

Instance methods inherited from struct `Value`

Instance methods inherited from class `Object`

, , , , , , , , , , , , , , , , , , , , , , , , , ,

Class methods inherited from class `Object`

Macros inherited from class `Object`

, , , , , , , , , , , , , , , , , , ,

Instance Method Detail

def abrt? #

Returnstrue if this enum value equalsABRT

def alrm? #

Returnstrue if this enum value equalsALRM

def bus? #

Returnstrue if this enum value equalsBUS

def chld? #

Returnstrue if this enum value equalsCHLD

def cont? #

Returnstrue if this enum value equalsCONT

def fpe? #

Returnstrue if this enum value equalsFPE

def hup? #

Returnstrue if this enum value equalsHUP

def ignore : Nil #

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

Note that trying to ignoreCHLD will actually set the default crystal handler that monitors and reaps child processes. This prevents zombie processes and is required byProcess#wait for example.

def ill? #

Returnstrue if this enum value equalsILL

def int? #

Returnstrue if this enum value equalsINT

def io? #

Returnstrue if this enum value equalsIO

def iot? #

Returnstrue if this enum value equalsIOT

def kill? #

Returnstrue if this enum value equalsKILL

def pipe? #

Returnstrue if this enum value equalsPIPE

def pwr? #

Returnstrue if this enum value equalsPWR

def quit? #

Returnstrue if this enum value equalsQUIT

def reset : Nil #

Resets the handler for this signal to the OS default.

Note that trying to resetCHLD will actually set the default crystal handler that monitors and reaps child processes. This prevents zombie processes and is required byProcess#wait for example.

def segv? #

Returnstrue if this enum value equalsSEGV

def stkflt? #

Returnstrue if this enum value equalsSTKFLT

def stop? #

Returnstrue if this enum value equalsSTOP

def sys? #

Returnstrue if this enum value equalsSYS

def term? #

Returnstrue if this enum value equalsTERM

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 thatCHLD is always trapped and child processes will always be reaped before the custom handler is called, hence a customCHLD handler must check child processes usingProcess.exists?. Trying to use waitpid with a zero or negative value won't work.

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

def trap? #

Returnstrue if this enum value equalsTRAP

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? #

Returnstrue if this enum value equalsTSTP

def ttin? #

Returnstrue if this enum value equalsTTIN

def ttou? #

Returnstrue if this enum value equalsTTOU

def unused? #

Returnstrue if this enum value equalsUNUSED

def urg? #

Returnstrue if this enum value equalsURG

def usr1? #

Returnstrue if this enum value equalsUSR1

def usr2? #

Returnstrue if this enum value equalsUSR2

def vtalrm? #

Returnstrue if this enum value equalsVTALRM

def winch? #

Returnstrue if this enum value equalsWINCH

def xcpu? #

Returnstrue if this enum value equalsXCPU

def xfsz? #

Returnstrue if this enum value equalsXFSZ

Crystal

enum Signal

Overview

Portability

Defined in:

Enum Members

Instance Method Summary

Instance methods inherited from struct Enum

Constructor methods inherited from struct Enum

Class methods inherited from struct Enum

Macros inherited from struct Enum

Instance methods inherited from module Comparable(Enum)

Instance methods inherited from struct Value

Instance methods inherited from class Object

Class methods inherited from class Object

Macros inherited from class Object