NAME

Thread::Running - provide non-blocking check whether threads are running

SYNOPSIS

    use Thread::Running;      # exports running(), exited() and tojoin()
    use Thread::Running qw(running);   # only exports running()
    use Thread::Running ();   # threads class methods only

    my $thread = threads->new( sub { whatever } );
    while (threads->running( $thread )) {
    # do your stuff
    }

    $_->join foreach threads->tojoin;

    until (threads->exited( $tid )) {
    # do your stuff
    }

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.

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

This module adds three features to threads that are sorely missed by some: you can check whether a thread is running, whether it can be joined or whether it has exited without waiting for that thread to be finished (non-blocking).

CLASS METHODS

These are the class methods.

running

 @running = threads->running( @thread );  # list of threads still running

 while (threads->running( @tid )) {  # while at least 1 is still running
 # do your stuff
 }

The "running" class method allows you to check whether one or more threads are still running. It accepts one or more thread objects or thread ID's (as obtained by the threads::tid() method). It returns the thread ID's of the threads that are still running (in list context). In scalar context, it just returns 1 or 0 to indicate whether any of the indicated threads is still running.

tojoin

 warn "Come on and join!\n" if threads->tojoin( $thread );

 $_->join foreach threads->tojoin( @tid ); # join all joinable threads

The "tojoin" class method allows you to check whether one or more threads can be joined. It accepts one or more thread objects or thread ID's (as obtained by the threads::tid() method). It returns the thread objects of the threads that have exited and which can be join()ed (if called in list context). In scalar context, it just returns 1 or 0 to indicate whether any of the indicated threads can be joined.

exited

 @exited = threads->exited( @tid ); # list of threads that have exited

 until (threads->exited( @tid )) { # until at least 1 has exited
 # do your stuff
 }

The "exited" class method allows you to check whether one or more threads have stopped running. It accepts one or more thread ID's (as obtained by the threads::tid() method). It returns the thread ID's of the threads that have exited (in list context). In scalar context, it just returns 1 or 0 to indicate whether any of the indicated threads has exited.

CAVEATS

This module is dependent on the Thread::Exit module, with all of its CAVEATS applicable.

TODO

Examples should be added.

AUTHOR

Elizabeth Mattijsen, <liz@dijkmat.nl>.

Please report bugs to <perlbugs@dijkmat.nl>.

COPYRIGHT

Copyright (c) 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.

SEE ALSO

threads, Thread::Exit.