NAME

Thread::Suspend - Suspend and resume operations for threads

VERSION

This document describes Thread::Suspend version 1.23

SYNOPSIS

    use Thread::Suspend 'SIGUSR1';      # Set the suspension signal
    use Thread::Suspend;                #  Defaults to 'STOP'

    $thr->suspend();                    # Suspend a thread
    threads->suspend();                 # Suspend all non-detached threads
    threads->suspend($thr, $tid, ...);  # Suspend multiple threads using
                                        #   objects or TIDs

    $thr->is_suspended();               # Returns suspension count
    threads->is_suspended();            # Returns list of all suspended threads

    $thr->resume();                     # Resume a thread
    threads->resume();                  # Resume all threads
    threads->resume($thr, $tid, ...);   # Resume multiple threads

DESCRIPTION

This module adds suspend and resume operations for threads.

Suspensions are cumulative, and need to be matched by an equal number of resume calls.

Declaration

This module must be imported prior to any threads being created.

Suspension is accomplished via a signal handler which is used by all threads on which suspend operations are performed. The signal for this operation can be specified when this module is declared, and defaults to "SIGSTOP". Consequently, the application and its threads must not specify some other handler for use with the suspend signal.

use Thread::Suspend;: Declares this module, and defaults to using "SIGSTOP" for suspend operations.
use Thread::Suspend 'SIGUSR1';
use Thread::Suspend 'Signal' => 11;: Declares this module, and uses the specified signal for suspend operations. Signals may be specified by the same names or (positive) numbers as supported by kill().

Methods

$thr->suspend()

Adds 1 to the suspension count of the thread, and suspends its execution if running. Returns the threads object.

It is possible for a thread to suspend itself. This is useful for starting a thread early in an application, and having it "wait" until needed:

    sub thr_func
    {
        # Suspend until needed
        threads->self()->suspend();
        ...
    }

threads->suspend()

Adds 1 to the suspension count of all non-detached threads, and suspends their execution if running. Returns a list of those threads.

threads->suspend($thr, $tid, ...)

Adds 1 to the suspension count of the threads specified by their objects or TIDs (for non-detached threads), and suspends their execution if running. Returns a list of the corresponding threads objects affected by the call.

$thr->is_suspended()

Returns the suspension count for the thread.

threads->is_suspended()

Returns a list of currently suspended, non-detached threads.

$thr->resume()

Decrements the suspension count for a thread. The thread will resume execution if the count reaches zero. Returns the threads object.

threads->resume()

Decrements the suspension count for all currently suspended, non-detached threads. Those threads that reach a count of zero will resume execution. Returns a list of the threads operated on.

Given possible multiple levels of suspension, you can ensure that all (non-detached) threads are running using:

    while (threads->resume()) { }

threads->resume($thr, $tid, ...)

Decrements the suspension count of the threads specified by their objects or TIDs (for non-detached threads). Those threads that reach a count of zero will resume execution. Returns a list of the threads operated on.

CAVEATS

Subject to the limitations of "THREAD SIGNALLING" in threads.

A thread that has been suspended will not respond to any other signals or commands until its suspension count is brought back to zero via resume calls.

Any locks held by a thread when it is suspended will remain in effect. To alleviate this potential problem, lock any such variables as part of a limited scope that also contains the suspension call:

    {
        lock($var);
        $thr->suspend();
    }

Calling "->resume()" on an non-suspended thread is ignored.

Detached threads can only be operated upon if their threads object is used. For example, the following works:

    my $thr = threads->create(...);
    $thr->detach();
    ...
    $thr->suspend();  # or threads->suspend($thr);
    ...
    $thr->resume();   # or threads->resume($thr);

Threads that have finished execution are, for the most part, ignored by this module.

REQUIREMENTS

Perl 5.8.0 or later

threads 1.39 or later

threads::shared 1.01 or later

Test::More 0.50 or later (for installation)

AUTHOR

Jerry D. Hedden, <jdhedden AT cpan DOT org>

COPYRIGHT AND LICENSE

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