Elizabeth Mattijsen > Thread-Running-0.07 > Thread::Running

Download:
Thread-Running-0.07.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.07   Source  

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 methods only

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

    $_->join foreach threads->tojoin;

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

    sleep 1 while threads->running;

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).

METHODS ^

These are the methods.

running

 sleep 1 while threads->running; # wait until all threads stopped running

 sleep 1 while $thread->running; # wait until this thread stopped running

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

 while (running( @tid )) {  # subroutine: while at least 1 is still running
 # do your stuff
 }

The "running" 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).

If called as a class method or as a subroutine without parameters, then it will check all threads of which it knows. If called as an instance method without parameters, it will only check the thread associated with the object.

In list context it returns the thread ID's of the threads that are still running. In scalar context, it just returns 1 or 0 to indicate whether any of the (implicitely) indicated threads is still running.

tojoin

 sleep 1 until threads->tojoin; # wait until any thread can be joined

 sleep 1 until $thread->tojoin; # wait until this thread can be joined

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

 $_->join foreach threads->tojoin; # join all joinable threads

The "tojoin" method allows you to check whether one or more threads have finished executing and can be joined. It accepts one or more thread objects or thread ID's (as obtained by the threads::tid() method).

If called as a class method or as a subroutine without parameters, then it will check all threads of which it knows. If called as an instance method without parameters, it will only check the thread associated with the object.

In list context it returns thread objects of the threads that can be joined. In scalar context, it just returns 1 or 0 to indicate whether any of the (implicitely) indicated threads can be joined.

exited

 sleep 1 until $thread->exited; # wait until this thread exited

 sleep 1 until threads->exited; # wait until all threads exited

 @exited = threads->exited( @thread ); # threads that have exited

 until (exited( @tid )) { # subroutine: until all have exited
 # do your stuff
 }

The "exited" method allows you to check whether all of one or more threads have exited. It accepts one or more thread objects or thread ID's (as obtained by the threads::tid() method).

If called as a class method or as a subroutine without parameters, then it will check all threads of which it knows. If called as an instance method without parameters, it will only check the thread associated with the object.

In list context it returns the thread ID's of the threads that have exited. In scalar context, it just returns 1 or 0 to indicate whether all of the (implicitely) indicated threads have exited.

REQUIRED MODULES ^

 load (any)
 Thread::Exit (0.06)

CAVEATS ^

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

This module uses the load module to make sure that subroutines are loaded only when they are needed.

TODO ^

Examples should be added.

AUTHOR ^

Elizabeth Mattijsen, <liz@dijkmat.nl>.

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

COPYRIGHT ^

Copyright (c) 2003-2005 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, load.

syntax highlighting: