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

Thread::Deadlock->report( 'filename' );    # report to file
Thread::Deadlock->report( '' );            # do not report

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.

CLASS METHODS

There is one class method.

report

Thread::Deadlock->report( 'filename' );  # write to specific file

Thread::Deadlock->report( '' );          # disable reporting

$report = Thread::Deadlock->report;      # obtain current setting

The "report" 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, or to disable report writing altogether.

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.

SEE ALSO

threads, threads::shared.