/ 
Thread-Signal-1.01
/ Thread::Signal

NAME

Thread::Signal - deliver a signal to a thread

SYNOPSIS

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->signal( 'ALRM',$thread->tid ); # signal a single thread
Thread::Signal->signal( 'ALRM',-1 ); # signal all threads that allow this

print "Signal is registered\n" if Thread::Signal->registered( ,'ALRM' );

Thread::Signal->prime( qw(ALRM USR1 USR2) ); # needed in special cases

DESCRIPTION

                 *** 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, but can be easily persuaded to do so.

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.

CLASS METHODS

These are the class methods.

register

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.

unregister

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.

registered

$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.

signal

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.

prime

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.

use Thread::Signal->prime

By calling Thread::Signal->prime with the signal names that you want to be deliverable in chile threads.

register, then unregister

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.

OPTIMIZATIONS

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.

CAVEATS

Due to a bug in the implementation of CLONE in Perl 5.8.0, it is impossible to make the registration process automatic. Which may be a bonus.

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.

AUTHOR

Elizabeth Mattijsen, <liz@dijkmat.nl>.

Please report bugs to <perlbugs@dijkmat.nl>.

COPYRIGHT

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.

SEE ALSO

AutoLoader.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 372:

You forgot a '=back' before '=head1'