Sys::SigAction(3) User Contributed Perl Documentation Sys::SigAction(3)NAMESys::SigAction - Perl extension for Consistent Signal Handling
SYNOPSYS
#do something non-interupt able
use Sys::SigAction qw( set_sig_handler );
{
my $h = set_sig_handler( 'INT' ,'mysubname' ,{ flags => SA_RESTART } );
... do stuff non-interupt able
} #signal handler is reset when $h goes out of scope
or
#timeout a system call:
use Sys::SigAction qw( set_sig_handler );
eval {
my $h = set_sig_handler( 'ALRM' ,\&mysubname ,{ mask=>[ 'ALRM' ] ,safe=>1 } );
alarm(2)
... do something you want to timeout
alarm(0);
}; #signal handler is reset when $h goes out of scope
alarm(0);
if ( $@ ) ...
or
use Sys::SigAction;
my $alarm = 0;
eval {
my $h = Sys::SigAction::set_sig_handler( 'ALRM' ,sub { $alarm = 1; } );
alarm(2)
... do something you want to timeout
alarm(0);
};
alarm(0);
if ( $@ or $alarm ) ...
or
use Sys::SigAction;
my $alarm = 0;
Sys::SigAction::set_sig_handler( 'TERM' ,sub { "DUMMY" } );
#code from here on uses new handler.... (old handler is forgotten)
or
use Sys::SigAction qw( timeout_call );
if ( timeout_call( 5 ,sub { $retval = DoSomething( @args ); } )
{
print "DoSomething() timed out\n" ;
}
ABSTRACT
This module implements "set_sig_handler()", which sets up a signal
handler and (optionally) returns an object which causes the signal
handler to be reset to the previous value, when it goes out of scope.
Also implemented is "timeout_call()" which takes a timeout value and a
code reference, and executes the code reference wrapped with an alarm
timeout.
Finally, two convenience routines are defined which allow one to get
the signal name from the number -- "sig_name()", and get the signal
number from the name -- "sig_number()".
DESCRIPTION
Prior to version 5.8.0 perl implemented 'unsafe' signal handling. The
reason it is consider unsafe, is that there is a risk that a signal
will arrive, and be handled while perl is changing internal data
structures. This can result in all kinds of subtle and not so subtle
problems. For this reason it has always been recommended that one do
as little as possible in a signal handler, and only variables that
already exist be manipulated.
Perl 5.8.0 and later versions implements 'safe' signal handling on
platforms which support the POSIX sigaction() function. This is
accomplished by having perl note that a signal has arrived, but
deferring the execution of the signal handler until such time as it is
safe to do so. Unfortunately these changes can break some existing
scripts, if they depended on a system routine being interupted by the
signal's arrival. The perl 5.8.0 implementation was modified further
in version 5.8.2.
From the perl 5.8.2 perlvar man page:
The default delivery policy of signals changed in Perl 5.8.0
from immediate (also known as "unsafe") to deferred, also
known as "safe signals".
The implementation of this changed the "sa_flags" with which the signal
handler is installed by perl, and it causes some system routines (like
connect()) to return EINTR, instead of another error when the signal
arrives. The problem comes when the code that made the system call
sees the EINTR code and decides it's going to call it again before
returning. Perl doesn't do this but some libraries do, including for
instance, the Oracle OCI library.
Thus the 'deferred signal' approach (as implemented by default in perl
5.8 and later) results in some system calls being retried prior to the
signal handler being called by perl. This breaks timeout logic for
DBD-Oracle which works with earlier versions of perl. This can be
particularly vexing, the host on which a database resides is not
available: "DBI->connect()" hangs for minutes before returning an
error (and cannot even be interupted with control-C, even when the
intended timeout is only seconds). This is because SIGINT appears to
be deferred as well. The result is that it is impossible to implement
open timeouts with code that looks like this in perl 5.8.0 and later:
eval {
local $SIG{ALRM} = sub { die "timeout" };
alarm 2;
$sth = DBI->connect(...);
alarm 0;
};
alarm 0;
die if $@;
The solution, if your system has the POSIX sigaction() function, is to
use perl's "POSIX::sigaction()" to install the signal handler. With
"sigaction()", one gets control over both the signal mask, and the
"sa_flags" that are used to install the handler. Further, with perl
5.8.2 and later, a 'safe' switch is provided which can be used to ask
for safe(r) signal handling.
Using sigaction() ensures that the system call won't be resumed after
it's interrupted, so long as die is called within the signal handler.
This is no longer the case when one uses $SIG{name} to set signal
handlers in perls >= 5.8.0.
The usage of sigaction() is not well documented however, and in perl
versions less than 5.8.0, it does not work at all. (But that's OK,
because just setting $SIG does work in that case.) Using sigaction()
requires approximately 4 or 5 lines of code where previously one only
had to set a code reference into the %SIG hash.
Unfortunately, at least with perl 5.8.0, the result is that doing this
effectively reverts to the 'unsafe' signals behavior. It is not clear
whether this would be the case in perl 5.8.2, since the safe flag can
be used to ask for safe signal handling. I suspect this separates the
logic which uses the "sa_flags" to install the handler, and whether
deferred signal handling is used.
The reader should also note, that the behavior of the 'safe' attribute
is not consistent with what this author expected. Specifically, it
appears to disable signal masking. This can be examined further in the
t/safe.t and the t/mask.t regression tests. Never-the-less,
Sys::SigAction provides an easy mechanism for the user to recover the
pre-5.8.0 behavior for signal handling, and the mask attribute clearly
works. (see t/mask.t) If one is looking for specific safe signal
handling behavior that is considered broken, and the breakage can be
demonstrated, then a patch to t/safe.t would be most welcome.
This module wraps up the POSIX:: routines and objects necessary to call
sigaction() in a way that is as efficient from a coding perspective as
just setting a localized $SIG{SIGNAL} with a code reference. Further,
the user has control over the "sa_flags" passed to sigaction(). By
default, if no additional args are passed to sigaction(), then the
signal handler will be called when a signal (such as SIGALRM) is
delivered.
Since sigaction() is not fully functional in perl versions less than
5.8, this module implements equivalent behavior using the standard %SIG
array. The version checking and implementation of the 'right' code is
handled by this module, so the user does not have to write perl version
dependent code. The attrs hashref argument to set_sig_handler() is
silently ignored, in perl versions less than 5.8. This module has been
tested with perls as old as 5.005 on solaris.
It is hoped that with the use of this module, your signal handling
behavior can be coded in a way that does not change from one perl
version to the next, and that sigaction() will be easier for you to
use.
FUNCTIONSset_sig_handler()
$sig ,$handler ,$attrs
Install a new signal handler and (if not called in a void context)
returning a Sys::SigAction object containing the old signal handler,
which will be restored on object destruction.
$sig is a signal name (without the 'SIG') or number.
$handler is either the name (string) of a signal handler
function or a subroutine CODE reference.
$attrs if defined is a hash reference containing the
following keys:
flags => the flags the passed sigaction
ex: SA_RESTART (defined in your signal.h)
mask => the array reference: signals you
do not want delivered while the signal
handler is executing
ex: [ SIGINT SIGUSR1 ] or
ex: [ qw( INT USR1 ]
safe => A boolean value requesting 'safe' signal
handling (only in 5.8.2 and greater)
earlier versions will issue a warning if
you use this
NOTE: This breaks the signal masking
timeout_call()
$timeout ,$coderef
Given a code reference, and a timeout value (in seconds), timeout()
will (in an eval) setup a signal handler for SIGALRM (which will die),
set an alarm clock, and execute the code reference.
If the alarm goes off the code will be interupted. The alarm is
canceled if the code returns before the alarm is fired. The routine
returns true if the code being executed timed out. (was interrupted).
Exceptions thrown by the code executed are propagated out.
The original signal handler is restored, prior to returning to the
caller.
sig_name()
Return the signal name (string) from a signal number.
ex:
sig_name( SIGINT ) returns 'INT'
sig_number()
Return the signal number (integer) from a signal name (minus the SIG
part).
ex:
sig_number( 'INT' ) returns the integer value of SIGINT;
AUTHOR
Lincoln A. Baxter <lab-at-lincolnbaxter-dot-com>
COPYRIGHT
Copyright (c) 2004-2009 Lincoln A. Baxter
All rights reserved.
You may distribute under the terms of either the GNU General Public
License or the Artistic License, as specified in the Perl README file,
SEE ALSO
perldoc perlvar
perldoc POSIX
The dbd-oracle-timeout.pod file included with this module. This
includes a DBD-Oracle test script, which illustrates the use of this
module with the DBI with the DBD-Oracle driver.
perl v5.14.1 2009-01-24 Sys::SigAction(3)
