THR_SUSPEND(3C) Standard C Library Functions THR_SUSPEND(3C)
NAME
thr_suspend, thr_continue - suspend or continue thread execution
SYNOPSIS
cc -mt [
flag... ]
file...[
library... ]
#include <thread.h>
int thr_suspend(
thread_t target_thread);
int thr_continue(
thread_t target_thread);
DESCRIPTION
The
thr_suspend() function immediately suspends the execution of the
thread specified by
target_thread. On successful return from
thr_suspend(), the suspended thread is no longer executing. Once a
thread is suspended, subsequent calls to
thr_suspend() have no
effect.
The
thr_continue() function resumes the execution of a suspended
thread. Once a suspended thread is continued, subsequent calls to
thr_continue() have no effect.
A suspended thread will not be awakened by any mechanism other than a
call to
thr_continue(). Signals and the effect of calls to
mutex_unlock(3C),
rw_unlock(3C),
sema_post(3C),
cond_signal(3C), and
cond_broadcast(3C) remain pending until the execution of the thread
is resumed by
thr_continue().
RETURN VALUES
If successful, the
thr_suspend() and
thr_continue() functions return
0. Otherwise, a non-zero value is returned to indicate the error.
ERRORS
The
thr_suspend() and
thr_continue() functions will fail if:
ESRCH The
target_thread cannot be found in the current process.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | MT-Safe |
+---------------+-----------------+
SEE ALSO
thr_create(3C),
thr_join(3C),
attributes(7),
standards(7)WARNINGS
The
thr_suspend() function is extremely difficult to use safely
because it suspends the target thread with no concern for the target
thread's state. The target thread could be holding locks, waiting
for a lock, or waiting on a condition variable when it is
unconditionally suspended. The thread will not run until
thr_continue() is applied, regardless of any calls to
mutex_unlock(),
cond_signal(), or
cond_broadcast() by other threads. Its existence on
a sleep queue can interfere with the waking up of other threads that
are on the same sleep queue.
The
thr_suspend() and
thr_continue() functions should be avoided.
Mechanisms that involve the cooperation of the targeted thread, such
as mutex locks and condition variables, should be employed instead.
March 22, 2002 THR_SUSPEND(3C)
