xnu-2422.1.72.tar.gz

[apple/xnu.git] / osfmk / man / thread_suspend.html

<h2>thread_suspend</h2>
<hr>
<p>
<strong>Function</strong> - Suspend a thread.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   thread_suspend</strong>
                <strong>(thread_act_t</strong>                     <var>target_thread</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>target_thread</var> 
<dd>
[in thread send right]
The thread to be suspended.
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>thread_suspend</strong> function increments the suspend
count for <var>target_thread</var> 
and prevents the thread from executing any more user-level instructions.
<p>
In this context, a user-level instruction can be either a machine instruction
executed in user mode or a system trap instruction, including
a page fault.  If a 
thread is currently executing within a system trap, the kernel
code may continue 
to execute until it reaches the system return code or it may
suspend within the 
kernel code.  In either case, the system trap returns when the thread resumes. 
<p>
To resume a suspended thread, use <strong>thread_resume</strong>.  If
the suspend count is 
greater than one, <strong>thread_resume</strong> must be repeated that
number of times.
<h3>CAUTIONS</h3>
<p>
Unpredictable results may occur if a program suspends a thread and alters its 
user state so that its direction is changed upon resuming.  Note that the
<strong>thread_abort</strong> function allows a system call to be aborted
only if it is progressing in a 
predictable way.
<h3>RETURN VALUES</h3>
<p>
Only generic errors apply.
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="task_resume.html"><strong>task_resume</strong></a>,
<a href="task_suspend.html"><strong>task_suspend</strong></a>,
<a href="thread_abort.html"><strong>thread_abort</strong></a>,
<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
<a href="thread_info.html"><strong>thread_info</strong></a>,
<a href="thread_resume.html"><strong>thread_resume</strong></a>,
<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
<a href="thread_terminate.html"><strong>thread_terminate</strong></a>.