te
Copyright (c) 2001 Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
thr_suspend, thr_continue - suspend or continue thread execution

cc -mt [ flag... ] file...[ library... ]
#include <thread.h>

int thr_suspend(thread_t target_thread);

int thr_continue(thread_t target_thread);

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().

If successful, the thr_suspend() and thr_continue() functions return 0. Otherwise, a non-zero value is returned to indicate the error.

The thr_suspend() and thr_continue() functions will fail if: ESRCH

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

MT-Level MT-Safe

thr_create (3C), thr_join (3C), attributes (7), standards (7)

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.