Thread::Deadlock - report deadlocks with stacktrace
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)
*** 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.
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.
use
Thread::Deadlock->on;
The "on" class method switches reporting on for the current thread and any threads that are created from this thread.
Thread::Deadlock->off;
The "off" class method switches reporting off for the current thread and any threads that are created from this thread.
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.
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.
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.
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.
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 = 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.
Thread::Deadlock->output( 'filename' ); # write to specific file $output = Thread::Deadlock->output; # obtain current setting
The "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.
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.
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.
undef
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.
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.
Elizabeth Mattijsen, <liz@dijkmat.nl>.
Please report bugs to <perlbugs@dijkmat.nl>.
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.
threads, threads::shared.
To install Thread::Deadlock, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Thread::Deadlock
CPAN shell
perl -MCPAN -e shell install Thread::Deadlock
For more information on module installation, please visit the detailed CPAN module installation guide.