NAME

Thread::State - check threads state, context, priority

SYNOPSIS

 use threads;
 use Thread::State;
 
 my $thr  = threads->new(sub { ... });
 
 while ( $thr->is_running ) {
   ...
 }
 
 if( $thr->wantarray ){
     ...
 }
 
 if ($thr->is_joined) {
   ...
 }

 if ($thr->is_joinable) {
   ...
 }

 if ($thr->is_not_joined_or_detached) { # until version 0.07, this method was is_joinable().
   ...
 }

 
 print threads->is_detached; # main thread is detached.

 ...

 # get thread priority
 my $priority = $thr->priority;
 # set thread priority (WIN32 thread only)
 $thr->priority(2);

DESCRIPTION

**************************** CAUTION ********************************

Since CPAN threads version 1.34, threads module has some new methods which are offered by Thread::State: is_running, is_detached, is_joinable and wantarray. On such a version, you can still use this module.

*********************************************************************

This module adds some methods to threads which are used to check threads' state (is detached? joined? finished?) and created context, code reference(start function) and thread priority.

Thread::Running is also for the same aim. It hacks threads::new, threads::join, and threads::detach. On the other hand, Thread::State peeks at the ithread structures directly.

You must use threads before using Thread::State.

This module requires Perl core threads (<= 1.07) or CPAN threads (>= 1.23).

METHODS

All below methods can be used as class methods. In that case, they return a current thread's state.

is_running

The thread is not finished.

is_finished

The thread is finished.

is_joined

The thread is joined.

is_detached

The thread is detached.

is_joinable

The thread is joinable (not joined, not detached and already finished). This behavior was changed in Thread::State 0.08 and previous method is is_not_joined_nor_detached;

is_not_joined_nor_detached

The thread is joinable (not joined, not detached) but might not finished yet.

wantarray

Returns the created context of the thread. As like wantarray, if void context, returns undef, list context is true value, and scalar context is false. in_context is alias to this method.

coderef

Returns the thread coderef which was passed into create or new. When a thread code is finished with threads core version, the coderef refcount is made to 0 and destroyed. In that case coderef method will return undef.

priority

priority($int)

Note: This method is experimental and may be removed.

Returns the thread priority. You can pass the integer to set new priority (the old priority is returned). But setting priority will be meaningful on Win32 machine, because to pthread implemented ithread, only 0 is acceptable.

When method fails in setting/getting priority, returns undef.

NOTE

With Perl 5.8.0 on Windows, is_joined and is_joinable may not work correctly. This is the problem of threads itself.

This problem was fixed by Thread::State 0.04.

SEE ALSO

Thread::Running, threads

AUTHOR

Makamaka Hannyaharamitu, <makamaka[at]donzoko.net>

COPYRIGHT AND LICENSE

Copyright 2006 by Makamaka Hannyaharamitu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.