NAME
Linux::Event::Signal - subclass-defined Linux signalfd subscriptions
SYNOPSIS
package LE::Shutdown;
use parent 'Linux::Event::Signal';
use POSIX qw(SIGINT SIGTERM);
sub on_signal ($signal, $number, $count) {
$signal->data->{server}->close;
$signal->loop->stop;
}
package main;
my $shutdown = $loop->add(LE::Shutdown->new(
signals => [SIGINT, SIGTERM], # required
data => { server => $server }, # optional
));DESCRIPTION
Linux::Event::Signal is the public subclassing boundary for synchronous Linux signal delivery. Concrete subclasses define one named on_signal method. Instances attach through $loop->add($signal) or loop => $loop, matching Stream, Listener, and Timer.
Each Loop lazily owns one private signalfd. An object may subscribe to several signal numbers, and several objects on that Loop may subscribe to the same number. Every matching object receives the complete count observed in one drain; counts are broadcast, never divided among subscribers.
DEFINING A SIGNAL TYPE
sub on_signal ($signal, $number, $count) {
$signal->data->{received}{$number} += $count;
$signal->loop->stop;
}The resolved callback is cached once per subclass. $number is the numeric signal and $count is the number of signalfd records aggregated for it in the current drain. Standard non-real-time signals may coalesce in the kernel before signalfd observes them. Real-time signals remain queued individually.
CONSTRUCTION
new(signals => $number | \@numbers, data => $value)
Creates a detached subscription for one or more positive numeric signals. Duplicates are removed while preserving their first occurrence. SIGKILL and SIGSTOP are rejected because Linux cannot block or deliver them through signalfd.
loop optionally attaches the object before new returns. data retains an arbitrary application value while the object is active or unattached.
METHODS
cancel
Idempotently removes every subscription, releases retained data, and makes the object terminal. Cancellation during on_signal is safe. The native mask retains a signal until the last object on that Loop cancels it.
signals
Returns a new array reference containing the subscribed numeric signals.
data([$value])
Gets or replaces application data while the object is nonterminal.
loop
Returns the owning Loop while active, otherwise undef.
state
Returns unattached, active, or cancelled.
is_active / is_terminal
Report the current lifecycle category.
MASK OWNERSHIP AND THREADS
On first subscription, Linux::Event blocks that signal in the thread attaching the object and records whether it was already blocked. On last cancellation it restores only mask entries that Linux::Event changed; signals blocked by the application remain blocked. A signal number may belong to only one Loop in a process, because reading one signalfd consumes its notification.
Linux::Event changes the thread mask but does not replace the signal disposition. Do not combine a Signal subscription with a Perl %SIG handler for the same number; signalfd consumes the blocked notification.
Signal masks are per-thread. Attach Signal objects before starting application threads so those threads inherit the blocked mask, or explicitly block the same signals in every application thread. Linux::Event's private resolver workers block signals themselves and cannot consume application signals. This feature uses native pthread APIs and does not require a Perl built with ithreads.
Fork before attaching Signal objects. Signal services are intentionally not reused across fork.