osfmk/man/thread_suspend.html

   1 <h2>thread_suspend</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Suspend a thread.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   thread_suspend</strong>
   8                 <strong>(thread_act_t</strong>                     <var>target_thread</var><strong>);</strong>
   9 </pre>
  10 <h3>PARAMETERS</h3>
  11 <dl>
  12 <p>
  13 <dt> <var>target_thread</var>
  14 <dd>
  15 [in thread send right]
  16 The thread to be suspended.
  17 </dl>
  18 <h3>DESCRIPTION</h3>
  19 <p>
  20 The <strong>thread_suspend</strong> function increments the suspend
  21 count for <var>target_thread</var>
  22 and prevents the thread from executing any more user-level instructions.
  23 <p>
  24 In this context, a user-level instruction can be either a machine instruction
  25 executed in user mode or a system trap instruction, including
  26 a page fault.  If a
  27 thread is currently executing within a system trap, the kernel
  28 code may continue
  29 to execute until it reaches the system return code or it may
  30 suspend within the
  31 kernel code.  In either case, the system trap returns when the thread resumes.
  32 <p>
  33 To resume a suspended thread, use <strong>thread_resume</strong>.  If
  34 the suspend count is
  35 greater than one, <strong>thread_resume</strong> must be repeated that
  36 number of times.
  37 <h3>CAUTIONS</h3>
  38 <p>
  39 Unpredictable results may occur if a program suspends a thread and alters its
  40 user state so that its direction is changed upon resuming.  Note that the
  41 <strong>thread_abort</strong> function allows a system call to be aborted
  42 only if it is progressing in a
  43 predictable way.
  44 <h3>RETURN VALUES</h3>
  45 <p>
  46 Only generic errors apply.
  47 <h3>RELATED INFORMATION</h3>
  48 <p>
  49 Functions:
  50 <a href="task_resume.html"><strong>task_resume</strong></a>,
  51 <a href="task_suspend.html"><strong>task_suspend</strong></a>,
  52 <a href="thread_abort.html"><strong>thread_abort</strong></a>,
  53 <a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
  54 <a href="thread_info.html"><strong>thread_info</strong></a>,
  55 <a href="thread_resume.html"><strong>thread_resume</strong></a>,
  56 <a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
  57 <a href="thread_terminate.html"><strong>thread_terminate</strong></a>.