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

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::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::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)

CLASS METHODS

These are the class methods.

every

Thread::Status->every( 5 );         # default, report every 5 seconds

Thread::Status->every( 0 );         # do not create reports automatically

$every = Thread::Status->every;

The "every" 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 setting

The "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 setting

The "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.

start

Thread::Status->start;

The "start" class method starts the thread that will perform the status monitoring. It can only be called once (or again after method stop was called). Reports will be generated automatically depending on values previously set with methods every, callers, shorten, output, format and encoding.

report

Thread::Status->report;

$report = Thread::Status->report;

The "report" class method can be called in two ways:

in void context

Generates a status report depending on values previously set with methods every, callers, shorten, output, format and encoding.

in scalar context

Creates a data-structure of the status of all of the threads and returns a reference to it. The data-structure has the following format:

- hash, keyed to thread id, filled with
-  a reference to a list for each of the callers, in which element is
-   a reference to a list with thread id and all of the fields of caller()

so that:

foreach my $tid (sort {$a <=> $b} keys %{$report}) {
  print "Thread $tid:\n";
  my $level = 0;
  foreach my $level (@{$report->{$tid}}) {
    print "  Level $level: $level->[2], line $level->[3]\n";
  }
}

will give you an overview of the status.

stop

The "stop" class method stops the thread that performs the status monitoring. It can only be called after method start has been called.

monitor_tid

$tid = Thread::Status->monitor_tid;

The "monitor_tid" class method returns the thread id of the thread that performs the status monitoring.

monitor_pid

$pid = Thread::Status->monitor_pid;

The "monitor_pid" class method returns the process id of the thread that performs the status monitoring.

OPTIMIZATIONS

This module uses load 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-2003 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, Thread::Signal.

cpanm Thread::Status

perl -MCPAN -e shell
install Thread::Status