The uploaded file
Thread-Status-0.02.tar.gz
has entered CPAN as
file: $CPAN/authors/id/E/EL/ELIZABETH/Thread-Status-0.02.tar.gz
size: 9683 bytes
md5: 3f996aa837a1a560913a635bab5093b0
=head1 NAME
Thread::Status - report stack status of all running threads
=head1 SYNOPSIS
perl -MThread::Status program # send SIGHUP for standard report to STDERR
use Thread::Status; # start monitoring using default settings
use Thread::Status
every => 1, # defaults to every 5 seconds
callers => 4, # defaults to 0
shorten => 0, # defaults to 1
format => 'xml', # defaults to 'plain'
output => 'filename', # defaults to STDERR
signal => 'HUP', # default
; # starts monitoring automatically
use Thread::Status (); # don't start anything yet
Thread::Status->every( 1 ); # every second
Thread::Status->every( 0 ); # disable, must signal manually
$every = Thread::Status->every;
Thread::Status->callers( 0 ); # default, show no caller lines
Thread::Status->callers( 4 ); # show 4 caller lines
$callers = Thread::Status->callers;
Thread::Status->shorten( 1 ); # default: shorten package names
Thread::Status->shorten( 0 ); # do not shorten package names
$shorten = Thread::Status->shorten;
Thread::Status->output( 'filename' );
$output = Thread::Status->output;
Thread::Status->format( 'plain' ); # default
Thread::Status->format( 'xml' ); # report in XML format
$format = Thread::Status->format;
Thread::Status->encoding('iso-latin-1'); # only needed for XML format
$encoding = Thread::Status->encoding;
Thread::Status->signal( 'USR1' ); # only once, before monitoring starts
$signal = Thread::Status->signal;
Thread::Status->start; # starts monitoring
Thread::Status->report; # status in format to output desired
$report = Thread::Status->report; # hash reference with all information
Thread::Status->stop; # stops monitoring
$tid = Thread::Status->monitor_tid; # thread id of monitoring thread
$pid = Thread::Status->monitor_pid; # process id of monitoring thread
=head1 DESCRIPTION
The Thread::Status module is mainly intended as a debugging aid for developers
of threaded programs. It can generate a report of where processing is
occurring in all available threads, either automatically every X seconds, or
by the application of an external signal, or under program control.
The good thing is that you do B<not> need to change your program in any way.
By a smart use of signals, the code running in each thread is interrupted to
report its status. And that is immediately the bad news: signals in threads
currently B<only work under Linux>.
To get a status report sent to STDERR every 5 seconds, simply add:
-MThread::Status
to the command line. So, if you would call your program with:
perl yourprogram parameters
then
perl -MThread::Status yourprogram parameters
will report the status of all the thread every 5 seconds on STDERR.
If you would like to have e.g. the output appear in a file with e.g. two levels
of caller information, you can specify the parameters on the command line as
well:
perl -MThread::Status=output,filename,callers,2 yourprogram parameters
A typical output would be:
0: line 19 in test1 (main)
0: line 23 in test1 (main::run_the_threads in main)
2: line 15 in test1 (main)
0: line 17 in test1 (threads::new in main)
0: line 23 in test1 (main::run_the_threads in main)
3: line 11 in test1 (main)
2: line 13 in test1 (threads::new in main)
0: line 17 in test1 (threads::new in main)
