Thread::Signal - deliver a signal to a thread
use Thread::Signal; # don't activate any signal yet use Thread::Signal ALRM => sub { warn "Alarm went off\n" }; Thread::Signal->register; # activate all from parent thread Thread::Signal->register( ALRM => sub { warn "Alarm went off\n" } ); Thread::Signal->unregister; # dis-allow all signalling from other threads Thread::Signal->unregister( qw(ALRM) ); # only dis-allow specific signals Thread::Signal->automatic( 'USR1' ); # auto-register in new threads Thread::Signal->unautomatic; # don't auto-register any Thread::Signal->unautomatic( 'USR1' ); # don't auto-register specific Thread::Signal->signal( 'ALRM',$thread->tid ); # signal a single thread Thread::Signal->signal( 'ALRM',-1 ); # signal all threads that allow this $registered = Thread::Signal->registered( 'ALRM' ); # check own thread $registered = Thread::Signal->registered( $tid,qw(ALRM USR2) ); # other thread Thread::Signal->prime( qw(ALRM USR1 USR2) ); # needed in special cases
*** A note of CAUTION *** This module only functions on Perl versions 5.8.0 and later. And then only when threads are enabled with -Dusethreads. It is of no use with any version of Perl before 5.8.0 or without threads enabled. *************************
The Thread::Signal module allows you to deliver signals to any thread. Unfortunately, this only works under Linux so far.
Signals are specified by their name (see %SIG in perlvar) and a subroutine specification (either a name or a reference).
Threads do not inherit signals from their parents by default, but can be easily persuaded to do so either automatically or on a thread-by-thread basis.
Threads can activate and de-activate the signals that they want to be deliverable to them. Any thread can check any other thread's deliverable signals.
These are the class methods.
Thread::Signal->register; # assume any signals from parent thread Thread::Signal->register( ALRM => sub { die "Alarm went off\n" } );
If you want a thread to be susceptible to signalling from other threads, you must register the thread with the Thread::Signal package. You only need to call this class method once, usually as one of the first things to do in a thread.
All signals that the parent thread has registered, will be registered for this thread also when you call this class method. If you want to start a new set of signals for this thread and all the threads created from this thread, you must call unregister first.
If you specify parameters, they should be specified as a parameter hash with the keys being the signal names and the values being the subroutines that should be executed when the signal is delivered. Subroutines can be specified as a subroutine name (assume the current namespace if none specified) or as a code reference to an (anonymous) subroutine.
You can also register signals with use Thread::Signal.
use Thread::Signal
Thread::Signal->unregister; # remove all Thread::Signal->unregister( qw(USR1 USR2) ); # remove specific only
Unregisters signals from registration with the Thread::Signal package for the current thread. By default, all signals that are currently registered for this thread (or implicetely by the parent thread) will be removed.
If you specify parameters, they should be the signal names for which you wish to remove the registration. In that case, only the specified signals will be unregistered.
Call register with specific signal names again at a later time to allow those signals to be delivered from other threads again.
Thread::Signal->automatic( qw(ALRM USR1) ); @automatic = Thread::Signal->automatic;
The "automatic" class method sets and returns the names of the signals that will be automatically registered when a new thread is started. Please note that signals must have been registered at least once by any of the parent threads for the signals to actually be active inside the new threads.
Call method unautomatic to remove signals from being automatically registered in newly created threads.
Thread::Signal->unautomatic; # no signal will be registered automatically Thread::Signal->unautomatic( qw(ALRM USR1) ); @automatic = Thread::Signal->unautomatic;
The "unautomatic" class method removes the names of the signals that will be automatically registered when a new thread is started. Calling this method for a signal only makes sense if method automatic was called earlier for the same signal. All signals that will be automatically registered, will be removed if this method is called without parameters.
All signals that are automatically registered are returned.
Call method automatic to add signal names for automatic registration again.
$registered = Thread::Signal->registered( 'ALRM' ); # one signal, this thread $registered = Thread::Signal->registered( $tid,qw(USR1 USR2) );
The "registered" class method returns whether the current thread has registered the indicated signal(s) with this or another thread.
If only one parameter is specified, it indicates the signal name to check for with the registration of the current thread.
If more than one parameter is specified, then the first parameter specified indicates the thread id to check and the other parameters indicate the signal names that should be checked for that thread.
A true value will only be returned if all specified signal names are registered with the indicated thread. In all other cases, a false value will be returned.
Thread::Signal->signal( 'ALRM',-1 ); # signal all registered threads Thread::Signal->signal( 'ALRM',@tid ); # deliver signal to specific threads
The "signal" class method acts exactly the same as the kill() function, except you must specify thread id's instead of process id's.
The special value -1 specifies that all registered threads should be signalled.
Thread::Signal->prime( qw(ALRM USR2) ); # circumvent bug in 5.8.0
Because of a bug/feature in Perl 5.8.0, a signal (in the %SIG hash) must be assigned in a thread if any of the threads that are created by that thread, want to reliably use that signal.
In most cases you don't have to worry about this. However, if you do have a situation in which you do not want a signal to be deliverable to the parent thread, but you do want to have those signals deliverable by the child threads, you basically have two options.
By calling Thread::Signal->prime with the signal names that you want to be deliverable in child threads.
You can also first register all of the signals with the appropriate handling routines, start the child threads in which you want the signals to be deliverable, and then call unregister without parameters to have the signals unregistered for the current thread.
This module uses AutoLoader to reduce memory and CPU usage. This causes subroutines only to be compiled in a thread when they are actually needed at the expense of more CPU when they need to be compiled. Simple benchmarks however revealed that the overhead of the compiling single routines is not much more (and sometimes a lot less) than the overhead of cloning a Perl interpreter with a lot of subroutines pre-loaded.
This module only runs on systems that use a (pseudo) process for each thread. To my knowledge, this happens only on Linux systems. I'd be interested in knowing about other OS's on which this implementation also works, so that I can add these to the documentation.
Because of a bug with signalling in Perl 5.8.0, an entry in the %SIG hash must have been assigned in a thread before it can be used in any of the threads started from that thread. The prime class method gives you an easy way to do that.
Elizabeth Mattijsen, <liz@dijkmat.nl>.
Please report bugs to <perlbugs@dijkmat.nl>.
Copyright (c) 2002 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
AutoLoader.
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
To install Thread::Signal, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Thread::Signal
CPAN shell
perl -MCPAN -e shell install Thread::Signal
For more information on module installation, please visit the detailed CPAN module installation guide.