NAME
Thread::Suspend - suspend and resume threads from another thread
SYNOPSIS
use Thread::Suspend; # exports suspend() and resume()
use Thread::Suspend qw(suspend); # only exports suspend()
use Thread::Suspend (); # threads class methods only
my $thread = threads->new( sub { whatever } );
$thread->suspend; # suspend thread by object
threads->suspend( $thread ); # also
threads->suspend( $tid ); # suspend by thread ID
threads->suspend; # suspend all (other) threads
$thread->resume; # resume a single thread
threads->resume; # resume all suspended threadsDESCRIPTION
*** 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 one feauture to threads that are sorely missed by some: the capability to suspend execution of a thread and be able to resume it when needed afterwards.
METHODS
These are the methods.
suspend
$thread->suspend; # suspend execution of given thread
threads->suspend( $thread ); # same
threads->suspend( $thread->tid ); # same, but specified by thread ID
threads->suspend; # suspend all other threadsThe "suspend" method allows you to suspend the execution of one or more threads. 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 suspend all running threads but the current thread. This can only be done if Thread::Running has been loaded prior to loading Thread::Suspend.
If called as an instance method without parameters, it will only check the thread associated with the object.
If called in void context, then no check will be performed whether the specified threads are actually suspended. If called in scalar or list context, the call will block until all specified threads have indicated back that they've been suspended. Due to latency, this may take a little while. By default a 5 second timeout will be applied: if the threads still haven't indicated that they're suspended by then, then execution of the current thread will continue.
In list context it returns the thread ID's of the threads that have indicated that they have been suspended. In scalar context, it returns 1 or 0 to indicate whether all of the specified threads have indicated that they have been suspended.
resume
$thread->resume; # resume execution of this thread
threads->resume( $thread ); # same
threads->resome( $thread->tid); # same
threads->resume; # resume all threads that were suspendedThe "resume" method allows you to resume execution of one or more threads that were previously suspended. 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.
If called in void context, then no check will be performed whether the specified threads are actually resumed. If called in scalar or list context, the call will block until all specified threads have indicated back that they've been resumed. Due to latency, this may take a little while. By default a 5 second timeout will be applied: if the threads still haven't indicated that they've resumed by then, then execution of the current thread will continue.
In list context it returns thread id's of the threads that have resumed. In scalar context, it just returns 1 or 0 to indicate whether all of the (implicitely) indicated threads have resumed.
CAVEATS
This module is dependent on the Thread::Signal module, with all of its CAVEATS applicable.
WHY NOT USE "SIGSTOP" AND "SIGCONT"?
Many operating systems already support the signals SIGSTOP (for halting execution of a process) and SIGCONT (for continuing execution of a process). The reason I've decided not to use that, is that in that way, execution may be halted in critical sections of Perl. This seemed like a Very Bad Idea(tm). Therefore a more general approach involving locking on a shared array, was chosen.
TODO
Not sure whether some way for dis-allowing suspends inside a thread is needed. Possibly when locking of variables is involved. This will be added as the need arises.
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.