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',
);
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 reportDESCRIPTION
*** 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.
CLASS METHODS
There are only class methods. The class methods summary, callers, shorten, format, encoding and output 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.
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.
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 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.