NAME
Thread::Status - report stack status of all running threads
SYNOPSIS
perl -MThread::Status program # send SIGHUP for standard report to STDERR
use Thread::Status; # start monitoring using default settings
use Thread::Status
each => 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->each( 1 ); # every second
Thread::Status->each( 0 ); # disable, must signal manually
$each = Thread::Status->each;
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 threadDESCRIPTION
*** 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::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 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 only work under Linux.
To get a status report sent to STDERR every 5 seconds, simply add:
-MThread::Statusto the command line. So, if you would call your program with:
perl yourprogram parametersthen
perl -MThread::Status yourprogram parameterswill report the status of all the thread every 5 seconds on STDERR.
CLASS METHODS
These are the class methods.
each
Thread::Status->each( 5 ); # default, create every 5 seconds
Thread::Status->each( 0 ); # do not create reports automatically
$each = Thread::Status->each;The "each" class method sets and returns the number of seconds that will pass before the next report is automatically generated. By default a report will be created every 5 seconds. The value 0 can be used to indicate that no automatic reports should be generated.
callers
Thread::Status->callers( 0 ); # default, return no caller lines
Thread::Status->callers( 4 ); # return 4 callers
$callers = Thread::Status->callers;The "callers" class method sets and returns the number of callers that should be shown in the report. By default, no callers will be shown.
shorten
Thread::Status->shorten( 1 ); # default, shorten
Thread::Status->shorten( 0 ); # do not shorten package names
$shorten = Thread::Status->shorten;The "shorten" class method sets and returns whether package names should be shortened in the report. By default, package names will be shortened, to create a more readable report.
format
Thread::Status->format( 'plain' ); # default, make plain text report
Thread::Status->format( 'xml' ); # make xml report
$format = Thread::Status->format;The "format" class method sets and returns the format in which the report will be generated. By default, the report will be created in plain text. If you select 'xml', you may want to change the encoding setting of the XML that will be generated.
encoding
Thread::Status->encoding( 'iso-latin-1' ); # default
$encoding = Thread::Status->encoding;The "encoding" class method sets and returns the encoding in which the report will be generated if xml was selected as the format. By default, the report will be created in 'ISO-Latin-1' encoding.
output
Thread::Status->output( 'filename' ); # write to specific file
$output = Thread::Status->output; # obtain current settingThe "output" class method returns the current output setting for the thread report. It can also be used to set the name of the file to which the report will be written. The strings "STDOUT" and "STDERR" can be used to indicate standard output and standard error respectively.
signal
Thread::Status->signal( 'HUP' ); # default
$signal = Thread::Status->signal; # obtain current settingThe "signal" class method sets and returns the signal that will be used internally (and possibly externally if no automatic reports are generated). By default the HUP signal will be used.
Please note that the signal can only be changed if monitoring has not yet started.
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
This module relies on the Thread::Signal module. There are currently a number of limitations when using the Thread::Signal module. Check the CAVEATS section of that module for up-to-date information.
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.