Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Thread::Suspend(3)    User Contributed Perl Documentation   Thread::Suspend(3)

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)

SEE ALSO
       Thread::Suspend on MetaCPAN:
       <https://metacpan.org/release/Thread-Suspend>

       Code repository:	<https://github.com/jdhedden/Thread-Suspend>

       threads,	threads::shared

       Sample code in the examples directory of	this distribution on CPAN.

AUTHOR
       Jerry D.	Hedden,	<jdheddenA ATA cpanA DOTA org>

COPYRIGHT AND LICENSE
       Copyright 2006 -	2009 Jerry D. Hedden. All rights reserved.

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

perl v5.32.0			  2017-04-11		    Thread::Suspend(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CAVEATS | REQUIREMENTS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Thread::Suspend&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help