NAME

       Net::Server::SIG - adpf - Safer signal handling

SYNOPSIS

           use Net::Server::SIG qw(register_sig check_sigs);
           use IO::Select ();
           use POSIX qw(WNOHANG);

           my $select = IO::Select->new();

           register_sig(PIPE => 'IGNORE',
                        HUP  => 'DEFAULT',
                        USR1 => sub { print "I got a SIG $_[0]\n"; },
                        USR2 => sub { print "I got a SIG $_[0]\n"; },
                        CHLD => sub { 1 while waitpid(-1, WNOHANG) > 0; },
                        );

           # add some handles to the select
           $select->add(\*STDIN);

           # loop forever trying to stay alive
           while (1) {

               # do a timeout to see if any signals got passed us
               # while we were processing another signal
               my @fh = $select->can_read(10);

               my $key;
               my $val;

               # this is the handler for safe (fine under unsafe also)
               if (check_sigs()) {
                 # or my @sigs = check_sigs();
                 next unless @fh;
               }

               my $handle = $fh[@fh];

               # do something with the handle

           }

DESCRIPTION

       Signals prior in Perl prior to 5.7 were unsafe.  Since then signals have been implemented
       in a more safe algorithm.  Net::Server::SIG provides backwards compatibility, while still
       working reliably with newer releases.

       Using a property of the select() function, Net::Server::SIG attempts to fix the unsafe
       problem.  If a process is blocking on select() any signal will short circuit the select.
       Using this concept, Net::Server::SIG does the least work possible (changing one bit from 0
       to 1).  And depends upon the actual processing of the signals to take place immediately
       after the select call via the "check_sigs" function.  See the example shown above and also
       see the sigtest.pl script located in the examples directory of this distribution.

FUNCTIONS

       "register_sig($SIG => \&code_ref)"
           Takes key/value pairs where the key is the signal name, and the argument is either a
           code ref, or the words 'DEFAULT' or 'IGNORE'.  The function register_sig must be used
           in conjunction with check_sigs, and with a blocking select() function call --
           otherwise, you will observe the registered signal mysteriously vanish.

       "unregister_sig($SIG)"
           Takes the name of a signal as an argument.  Calls register_sig with a this signal name
           and 'DEFAULT' as arguments (same as register_sig(SIG,'DEFAULT')

       "check_sigs()"
           Checks to see if any registered signals have occurred.  If so, it will play the
           registered code ref for that signal.  Return value is array containing any SIGNAL
           names that had occurred.

       "sig_is_registered($SIG)"
           Takes a signal name and returns any registered code_ref for that signal.

AUTHORS

       Paul Seamons (paul@seamons.com)

       Rob B Brown (rob@roobik.com) - Provided a sounding board and feedback in creating
       Net::Server::SIG and sigtest.pl.

LICENSE

         This package may be distributed under the terms of either the
         GNU General Public License
           or the
         Perl Artistic License

         All rights reserved.