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)