share/man/man3c/thr_suspend.3c

   1 '\" te
   2 .\"  Copyright (c) 2001 Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH THR_SUSPEND 3C "Mar 22, 2002"
   7 .SH NAME
   8 thr_suspend, thr_continue \- suspend or continue thread execution
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ]
  13 #include <thread.h>
  14
  15 \fBint\fR \fBthr_suspend\fR(\fBthread_t\fR \fItarget_thread\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBint\fR \fBthr_continue\fR(\fBthread_t\fR \fItarget_thread\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBthr_suspend()\fR function immediately suspends the execution of the
  27 thread specified by \fItarget_thread\fR. On successful return from
  28 \fBthr_suspend()\fR, the suspended thread is no longer executing. Once a thread
  29 is suspended, subsequent calls to \fBthr_suspend()\fR have no effect.
  30 .sp
  31 .LP
  32 The \fBthr_continue()\fR function resumes the execution of a suspended thread.
  33 Once a suspended thread is continued, subsequent calls to \fBthr_continue()\fR
  34 have no effect.
  35 .sp
  36 .LP
  37 A suspended thread will not be awakened by any mechanism other than a call to
  38 \fBthr_continue()\fR.  Signals and the effect of calls
  39 to \fBmutex_unlock\fR(3C), \fBrw_unlock\fR(3C), \fBsema_post\fR(3C),
  40 \fBcond_signal\fR(3C), and \fBcond_broadcast\fR(3C) remain pending until the
  41 execution of the thread is resumed by \fBthr_continue()\fR.
  42 .SH RETURN VALUES
  43 .sp
  44 .LP
  45 If successful, the \fBthr_suspend()\fR and \fBthr_continue()\fR functions
  46 return  \fB0\fR. Otherwise, a non-zero value is returned to indicate the error.
  47 .SH ERRORS
  48 .sp
  49 .LP
  50 The \fBthr_suspend()\fR and \fBthr_continue()\fR functions will fail if:
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fBESRCH\fR \fR
  55 .ad
  56 .RS 10n
  57 The \fItarget_thread\fR cannot be found in the current process.
  58 .RE
  59
  60 .SH ATTRIBUTES
  61 .sp
  62 .LP
  63 See \fBattributes\fR(5) for descriptions of the following attributes:
  64 .sp
  65
  66 .sp
  67 .TS
  68 box;
  69 c | c
  70 l | l .
  71 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  72 _
  73 MT-Level        MT-Safe
  74 .TE
  75
  76 .SH SEE ALSO
  77 .sp
  78 .LP
  79 \fBthr_create\fR(3C), \fBthr_join\fR(3C), \fBattributes\fR(5),
  80 \fBstandards\fR(5)
  81 .SH WARNINGS
  82 .sp
  83 .LP
  84 The \fBthr_suspend()\fR function is extremely difficult to use safely because
  85 it suspends the target thread with no concern for the target thread's state.
  86 The target thread could be holding locks, waiting for a lock, or waiting on a
  87 condition variable when it is unconditionally suspended. The thread will not
  88 run until \fBthr_continue()\fR is applied, regardless of any calls to
  89 \fBmutex_unlock()\fR, \fBcond_signal()\fR, or \fBcond_broadcast()\fR by other
  90 threads. Its existence on a sleep queue can interfere with the waking up of
  91 other threads that are on the same sleep queue.
  92 .sp
  93 .LP
  94 The \fBthr_suspend()\fR and \fBthr_continue()\fR functions should be avoided.
  95 Mechanisms that involve the cooperation of the targeted thread, such as mutex
  96 locks and condition variables, should be employed instead.