NAME

Sidef::Sys::Sig - Signal handling interface for Sidef

DESCRIPTION

The Sig class provides an interface to system signals and special handlers in Sidef. It allows you to set and retrieve signal handlers, including both standard UNIX signals (like SIGINT, SIGTERM) and special pseudo-signals (__WARN__ and __DIE__) that handle warnings and exceptions.

Signal handlers are blocks of code that execute when a specific signal is received. This is useful for:

• Making warnings fatal

• Custom error handling

• Graceful shutdown on interrupts

• Cleaning up resources on termination

• Custom signal processing

SYNOPSIS

# Make warnings fatal
Sig.__WARN__ { |msg| die msg }

# Handle interrupt signal (Ctrl+C)
Sig.INT {
    say "Caught interrupt! Cleaning up..."
    # perform cleanup
    Sys.exit(0)
}

# Handle termination signal
Sig.TERM {
    say "Received termination signal"
    # save state and exit gracefully
}

# Custom error handler
Sig.__DIE__ { |error|
    say "Fatal error occurred: #{error}"
    # log error, send notification, etc.
}

# Retrieve current handler for a signal
var old_handler = Sig.INT

# Set new handler and restore old one later
Sig.INT { say "New handler" }
# ... do work ...
Sig.INT(old_handler)  # restore

# Ignore a signal
Sig.INT { nil }

METHODS

new

var sig = Sig.new

Creates and returns a new Sig object. In practice, you typically use the class methods directly rather than creating an instance.

Returns: A new Sig object

Signal Methods

The Sig class dynamically provides methods for all available system signals plus the special __WARN__ and __DIE__ handlers. Each signal method can be called in two ways:

Setting a Handler

Sig.SIGNAL_NAME { |arg|
    # handler code
}

Sets a handler block for the specified signal. The block receives signal-specific arguments:

• For __WARN__: receives the warning message string

• For __DIE__: receives the error message string

• For other signals: receives the signal name

Parameters:

• block - A code block to execute when the signal is received

Returns: The handler block or value that was set

Retrieving a Handler

var handler = Sig.SIGNAL_NAME

Retrieves the current handler for the specified signal.

Returns: The current signal handler (may be nil if no handler is set)

Common Signals

__WARN__

Sig.__WARN__ { |msg|
    # handle warning
}

Special pseudo-signal that handles Perl warnings. Useful for making warnings fatal or logging them.

Example - Make warnings fatal:

Sig.__WARN__ { |msg| die msg }

Example - Log warnings:

Sig.__WARN__ { |msg|
    File('warnings.log').append("#{Time.now}: #{msg}")
}

__DIE__

Sig.__DIE__ { |error|
    # handle fatal error
}

Special pseudo-signal that handles fatal errors before they terminate the program.

Example - Custom error logging:

Sig.__DIE__ { |error|
    say "FATAL: #{error}"
    File('error.log').append("#{Time.now}: #{error}")
}

INT

Sig.INT { |sig|
    # handle interrupt (Ctrl+C)
}

Handles interrupt signals, typically sent when the user presses Ctrl+C.

Example - Graceful shutdown:

var running = true

Sig.INT {
    say "\nInterrupt received, shutting down..."
    running = false
}

while (running) {
    # main program loop
}

TERM

Sig.TERM { |sig|
    # handle termination signal
}

Handles termination signals, typically sent by system shutdown or kill command.

Example:

Sig.TERM {
    say "Termination requested"
    # save state
    # close connections
    Sys.exit(0)
}

HUP

Sig.HUP { |sig|
    # handle hangup signal
}

Handles hangup signals, traditionally sent when a terminal connection is lost. Often used to reload configuration.

Example - Reload configuration:

Sig.HUP {
    say "Reloading configuration..."
    load_config()
}

ALRM

Sig.ALRM { |sig|
    # handle alarm signal
}

Handles alarm signals, typically used with alarm() for timeouts.

CHLD

Sig.CHLD { |sig|
    # handle child process termination
}

Handles signals sent when a child process terminates, stops, or resumes.

Other Signals

The Sig class supports all signals available on your system. Common ones include:

• QUIT - Quit signal (Ctrl+\)

• KILL - Force kill (cannot be caught)

• PIPE - Broken pipe

• USR1, USR2 - User-defined signals

• STOP - Stop process (cannot be caught)

• CONT - Continue process

Consult your system's signal documentation for a complete list.

EXAMPLES

Making Warnings Fatal

Sig.__WARN__ { |msg| die msg }

# Now warnings become fatal errors
var x = "abc" + 0  # Dies instead of just warning

Graceful Shutdown

var should_exit = false

Sig.INT {
    say "Shutting down gracefully..."
    should_exit = true
}

while (!should_exit) {
    # process work
    say "Working..."
    sleep(1)
}

say "Cleanup complete"

Timeout Handler

var timeout_reached = false

Sig.ALRM {
    timeout_reached = true
}

alarm(5)  # Set 5-second alarm

while (!timeout_reached) {
    # do work
}

say "Timeout!"

Custom Error Reporting

Sig.__DIE__ { |error|
    var log = File('error_log.txt')
    log.append("[#{Time.now}] ERROR: #{error}\n")
    say "An error occurred. Check error_log.txt"
}

Ignoring Signals

# Ignore interrupt signal
Sig.INT { nil }

# Now Ctrl+C won't terminate the program

Restoring Default Handlers

# Save original handler
var original = Sig.INT

# Set custom handler
Sig.INT { say "Custom handler" }

# Later, restore original
Sig.INT(original)

NOTES

• Signal handlers execute in the context where the signal is received, which may interrupt normal program flow

• Some signals (like SIGKILL and SIGSTOP) cannot be caught or handled

• Signal handler blocks should be brief and avoid complex operations

• The __WARN__ and __DIE__ handlers are Perl-specific pseudo-signals, not UNIX signals

• Setting a signal handler to nil effectively ignores that signal

• Signal behavior may vary across different operating systems

• Be cautious with signal handlers in multi-threaded programs

SEE ALSO

• Sidef::Sys::Sys - System interface

• perlipc - Perl interprocess communication (signals)

• signal(7) - Linux signal overview

AUTHOR

Daniel "Trizen" Șuteu

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Sidef itself.

cpanm Sidef

perl -MCPAN -e shell
install Sidef