osfmk/man/thread_abort_safely.html

   1 <h2>thread_abort_safely</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Abort a thread, restartably.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   thread_abort_safely</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 aborted.
  17 </dl>
  18 <h3>DESCRIPTION</h3>
  19 <p>
  20 The <strong>thread_abort_safely</strong> function aborts page faults and any message
  21 primitive calls in use by <var>target_thread</var>.  Scheduling depressions
  22 and clock sleeps are
  23 also aborted.  The call returns a code indicating that it was
  24 interrupted.  The call
  25 is interrupted even if the thread (or the task containing it)
  26 is suspended.  If it is
  27 suspended, the thread receives the interrupt when it resumes.
  28 <p>
  29 If its state is not modified before it resumes, the thread will
  30 retry an aborted
  31 page fault.  The Mach message trap returns either
  32 <strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending
  33 on whether the send or the
  34 receive side was interrupted.  Note, though, that the Mach message trap is
  35 contained within the <strong>mach_msg</strong> library routine, which,
  36 by default, retries
  37 interrupted message calls.
  38 <p>
  39 The basic purpose of <strong>thread_abort_safely</strong> is to let
  40 one thread cleanly stop
  41 another thread (<var>target_thread</var>).  The target thread is stopped
  42 in such a manner that
  43 its future execution can be controlled in a predictable way.  When
  44 <strong>thread_abort_safely</strong> returns (if successful), the target
  45 thread will appear to have just
  46 returned from the kernel (if it had been in kernel mode).
  47 <h3>NOTES</h3>
  48 <p>
  49 By way of comparison, the <strong>thread_suspend</strong> function keeps
  50 the target thread
  51 from executing any further instructions at the user level, including
  52 the return
  53 from a system call.  The <strong>thread_get_state</strong> function
  54 returns the thread's user
  55 state, while <strong>thread_set_state</strong> allows modification of the user state.
  56 <p>
  57 A problem occurs if a suspended thread had been executing within a system
  58 call.  In this case, the thread has, not only a user state, but
  59 an associated kernel
  60 state. (The kernel state cannot be changed with <strong>thread_set_state</strong>.)
  61 As a result,
  62 when the thread resumes, the system call can return, producing a change in the
  63 user state and, possibly, user memory.
  64 <p>
  65 For a thread executing within a system call, <strong>thread_abort_safely</strong>
  66 aborts the
  67 kernel call from the thread's point of view.  Specifically, it
  68 resets the kernel state so
  69 that the thread will resume execution at the system call return,
  70 with the return
  71 code value set to one of the interrupted codes.  The system call itself may
  72 completed entirely, aborted entirely or be partially completed,
  73 depending on when
  74 the abort is received.  As a result, if the thread's user state
  75 has been modified by
  76 <strong>thread_set_state</strong>, it will not be altered un-predictably
  77 by any unexpected
  78 system call side effects.
  79 <p>
  80 For example, to simulate a POSIX signal, use the following sequence of calls:
  81 <dl>
  82 <dd>
  83 <strong>thread_suspend</strong>\(emTo stop the thread.
  84 <dd>
  85 <strong>thread_abort_safely</strong>\(emTo interrupt any system call in
  86 progress and set the
  87 return value to "interrupted".  Because the thread is already stopped, it will
  88 not return to user code.
  89 <dd>
  90 <strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a
  91 procedure call to the signal handler.
  92 <dd>
  93 <strong>thread_resume</strong>\(emTo resume execution at the signal handler.
  94 If the thread's
  95 stack is set up correctly, the thread can return to the interrupted
  96 system call.
  97 Note that the code to push an extra stack frame and change the registers is
  98 highly machine dependent.
  99 </dl>
 100 <h3>CAUTIONS</h3>
 101 <p>
 102 As a rule, do not use <strong>thread_abort_safely</strong> on a non-suspended
 103 thread.  This
 104 operation is very risky because it is difficult to know which
 105 system trap, if any, is
 106 executing and whether an interrupt return will result in some useful action by
 107 the thread.
 108 <p>
 109 <strong>thread_abort_safely</strong> will not abort any non-atomic operation
 110 (such as a
 111 multi-page <strong>memory_object_data_supply</strong> or exception processing)
 112 but will return an
 113 error instead.  The caller of this function must then allow the
 114 thread to resume
 115 and attempt to abort it later.  If the thread must be aborted,
 116 even if doing so
 117 would abort any non-atomic operations, <strong>thread_abort</strong> would be used.
 118 <h3>RETURN VALUES</h3>
 119 <dl>
 120 <p>
 121 <dt> <strong>KERN_FAILURE</strong>
 122 <dd>
 123 The thread is in the middle of a non-restartable operation.
 124 </dl>
 125 <h3>RELATED INFORMATION</h3>
 126 <p>
 127 Functions:
 128 <a href="mach_msg.html"><strong>mach_msg</strong></a>,
 129 <a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
 130 <a href="thread_info.html"><strong>thread_info</strong></a>,
 131 <a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
 132 <a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
 133 <a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
 134 <a href="thread_abort.html"><strong>thread_abort</strong></a>.