NAME
Thread::Deadlock - report deadlocks with stacktrace
SYNOPSIS
perl -MThread::Deadlock program # report to STDERR
perl -MThread::Deadlock=filename program # report to file
use Thread::Deadlock; # report to STDERR
use Thread::Deadlock 'filename'; # report to file
use Thread::Deadlock (); # set up, need on() later
use Thread::Deadlock ( # call class methods easily
summary => 'auto',
callers => 4,
shorten => 1,
format => 'plain',
encoding => 'iso-latin-1',
output => 'STDERR',
trace => undef,
);
Thread::Deadlock->summary( 'auto' ); # default, automatic
Thread::Deadlock->summary( 0 ); # don't do summary
Thread::Deadlock->summary( 1 ); # do summary always
Thread::Deadlock->callers( 4 ); # default, show 4 lines in dump
Thread::Deadlock->callers( 0 ); # show all lines in dump
Thread::Deadlock->shorten( 1 ); # default: shorten package names
Thread::Deadlock->shorten( 0 ); # do not shorten package names
Thread::Deadlock->format( 'plain' ); # default, plain text format
Thread::Deadlock->format( 'xml' ); # set XML format
Thread::Deadlock->encoding('iso-latin-1'); # only needed for XML format
Thread::Deadlock->off; # disable in this thread
Thread::Deadlock->on; # enable again in this thread
$report = Thread::Deadlock->report; # return intermediate report
Thread::Deadlock->output( 'filename' ); # report to file
Thread::Deadlock->disable; # disable report
Thread::Deadlock->trace( 'filename' ); # start tracing to file
Thread::Deadlock->untrace; # stop tracing (default)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::Deadlock module allows you to find out where your threaded application may be deadlocked. It does not prevent any deadlocks, nor is it capable of resolving any deadlocks.
If you use the Thread::Deadlock module, all occurences of cond_wait(), cond_signal() and cond_broadcast() in the source are checkpointed to remember where it was exactly in your source and where it was in the execution stack. When your program finishes (either as intended or after you killed the program, e.g. by pressing Control-C), then a report will be generated for each thread, indicating where each thread had its last checkpoint. By default, this report is written to STDERR, but can be redirected to a file of your choice.
On top of this, it is also possible to have a trace generated of each time a cond_wait(), cond_signal() or cond_broadcast() was called. This may give additional information as to how a problem such as a deadlock, can occur.
CLASS METHODS
There are only class methods. The class methods summary, callers, shorten, format, encoding, output and trace methods can also be called as fields in a parameter hash with use.
on
Thread::Deadlock->on;The "on" class method switches reporting on for the current thread and any threads that are created from this thread.
off
Thread::Deadlock->off;The "off" class method switches reporting off for the current thread and any threads that are created from this thread.
summary
Thread::Deadlock->summary( 'auto' ); # default, automatic
Thread::Deadlock->summary( 0 ); # don't do summary
Thread::Deadlock->summary( 1 ); # always do summary
$summary = Thread::Deadlock->summary;The "summary" class method sets and returns whether a thread summary will be added to the report. By default, a summary will be added if there are at least two threads at the same location in the source.
callers
Thread::Deadlock->callers( 4 ); # default, return 4 callers
Thread::Deadlock->callers( 0 ); # return all callers
$callers = Thread::Deadlock->callers;The "callers" class method sets and returns the number of callers that should be shown in the report. By default, only 4 callers will be shown.
shorten
Thread::Deadlock->shorten( 1 ); # default, shorten
Thread::Deadlock->shorten( 0 ); # do not shorten package names
$shorten = Thread::Deadlock->shorten;The "shorten" class method sets and returns whether package names should be shortened in the dump. By default, package names will be shortened, to create a more readable report.
format
Thread::Deadlock->format( 'plain' ); # default, make plain text report
Thread::Deadlock->format( 'xml' ); # make xml report
$format = Thread::Deadlock->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::Deadlock->encoding( 'iso-latin-1' ); # default
$encoding = Thread::Deadlock->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.
report
$report = Thread::Deadlock->report;The "report" class method returns the report that is otherwise automatically created when the program finishes. It can be used for creation of intermediate reports. It can be called by _any_ thread.
output
Thread::Deadlock->output( 'filename' ); # write to specific file
$output = Thread::Deadlock->output; # obtain current settingThe "output" class method returns the current setting for the thread checkpoint report. It can also be used to set the name of the file to which the report will be written. Call disable to disable reporting.
The strings "STDOUT" and "STDERR" can be used to indicate standard output and standard error respectively.
disable
Thread::Deadlock->disable;The "disable" class method disables reporting altogether. This can be handy if your program has completed successfully and you're not interested in a report.
trace
Thread::Deadlock->trace( 'filename'); # start tracing to specific file
$trace = Thread::Deadlock->trace;The "trace" class method sets and returns the filename to which a trace will be appended. By default, no tracing occurs in which case undef will be returned. Call untrace to disable tracing for all threads.
The strings "STDOUT" and "STDERR" can be used to indicate standard output and standard error respectively.
disable
Thread::Deadlock->untrace;The "untrace" class method disables tracing for all threads. This can be handy if there are sections in your program that you do not want to have traced.
REQUIRED MODULES
load (any)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 was originally conceived as hi-jacking the core lock() function. However, this proved to be impossible, at least with Perl 5.8.0. It was therefore re-written to hi-jack the cond_wait(), cond_signal() and cond_broadcast() routines from threads::shared.pm. This is not exactly the same, but since most deadlocking problems are caused by mixups of cond_wait() and cond_signal()/cond_broadcast(), this seems to be as good a solution.
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.