thr_suspend(3scl)thr_suspend(3scl)NAMEthr_suspend - Suspend a thread's execution.
LIBRARY
SCL Threads Library (libthread.so)
SYNOPSIS
#include <thread.h>
int thr_suspend(
thread_t target_thread );
PARAMETERS
Identifier of the thread to be suspended.
DESCRIPTION
This routine suspends the execution of the specified thread.
A thread can suspend itself by calling this routine with its own thread
ID. However, if the thread suspending itself is the last non-suspended
thread in the process, then the thread is not suspended and the EDEADLK
status is returned.
If a thread is not suspending itself, then this routine does not return
until the target thread is suspended.
If the target thread is already suspended, then this routine returns 0.
A suspended thread does not resume execution until it is the target of
a thr_continue(3scl) call.
A suspended thread is not interrupted by signals; the signals are pend‐
ing until the thread resumes execution by being the target of a
thr_continue(3scl) call.
A thread can be created as suspended by specifying the THR_SUSPENDED
attribute in the flags parameter to thr_create(3scl).
Incautious use of thr_suspend(3scl) can cause an application to hang,
if, for example, a thread is suspended whilst it holds a mutex, which
causes other threads to block when they also try to lock the mutex.
SCL IMPLEMENTATION NOTES
POSIX threads does not support suspending and continueing a thread's
execution. Thus thr_suspend(3scl) is implemented by sending a signal to
the target thread by calling pthread_kill(3). When the thread being
suspended receives the signal, it sends an acknowledgement back to the
calling thread. The suspended thread then waits in the suspend signal-
handler until it gets a continue signal from thr_continue(3scl).
The SCL thread library maintains state information for each thread to
ensure that only non-suspended threads are sent the suspend signal, and
that only suspended threads are sent the continue signal. This avoids
the potential problem of a thread having both suspend and continue sig‐
nals pending, where the order of the signals is indeterminate.
By default SCL uses the SIGUSR1 signal for thr_suspend(3scl), and
SIGUSR2 for thr_continue(3scl). However, these signals may be used by
applications for their own purposes, and so SCL enables the user to
specify alternate signals to be used for thr_suspend(3scl) and thr_con‐
tinue(3scl). This is achieved by setting the environment variables
STL_SIG_SUSPEND and STL_SIG_CONTINUE to the integer values of alterna‐
tive signals before running the application program. The signals and
their values are listed in the man-page for signal(4), and in the file
/usr/include/signal.h.
E.g. to use SIGXCPU as the suspend signal, where SIGXCPU is defined as
value 24 in /usr/include/signal.h, issue a command like:
csh> setenv STL_SIG_SUSPEND 24
RETURN VALUES
If an error condition occurs, this routine returns an integer value
indicating the type of error.
Additional error return information may be written to the SCL error
log. Refer to scl_error_log(4scl) for details.
Possible return values are as follows: Successful completion. tar‐
get_thread specifies a non-existant thread ID. An internal implementa‐
tion error occurred. Refer to the SCL errorlog for additional informa‐
tion.
Note: when the SCL implementation of thr_suspend(3scl) returns ECAN‐
CELED, it does not have the Solaris meaning of a suspend operation
being cancelled because a subsequent thr_continue(3scl) occurred before
the suspend completed. Suspending target_thread would cause all the
threads in the process to be suspended.
ERRORS
None.
RELATED INFORMATION
Functions: pthread_kill(3), scl_intro(3scl), scl_thread_intro(3scl),
thr_create(3scl), thr_continue(3scl)
Files: scl_error_log(4scl), signal(4)
Manuals: Solaris Compatibility Libraries User's Guide
thr_suspend(3scl)
