xnu-344.tar.gz

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

<h2>thread_abort_safely</h2>\r<hr>\r<p>\r<strong>Function</strong> - Abort a thread, restartably.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t   thread_abort_safely</strong>\r                <strong>(thread_act_t</strong>                     <var>target_thread</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>target_thread</var> \r<dd>\r[in thread send right]\rThe thread to be aborted.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>thread_abort_safely</strong> function aborts page faults and any message\rprimitive calls in use by <var>target_thread</var>.  Scheduling depressions\rand clock sleeps are \ralso aborted.  The call returns a code indicating that it was\rinterrupted.  The call \ris interrupted even if the thread (or the task containing it)\ris suspended.  If it is \rsuspended, the thread receives the interrupt when it resumes.\r<p>\rIf its state is not modified before it resumes, the thread will\rretry an aborted \rpage fault.  The Mach message trap returns either\r<strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending\ron whether the send or the\rreceive side was interrupted.  Note, though, that the Mach message trap is \rcontained within the <strong>mach_msg</strong> library routine, which,\rby default, retries\rinterrupted message calls.\r<p>\rThe basic purpose of <strong>thread_abort_safely</strong> is to let\rone thread cleanly stop\ranother thread (<var>target_thread</var>).  The target thread is stopped\rin such a manner that \rits future execution can be controlled in a predictable way.  When\r<strong>thread_abort_safely</strong> returns (if successful), the target\rthread will appear to have just\rreturned from the kernel (if it had been in kernel mode).\r<h3>NOTES</h3>\r<p>\rBy way of comparison, the <strong>thread_suspend</strong> function keeps\rthe target thread \rfrom executing any further instructions at the user level, including\rthe return \rfrom a system call.  The <strong>thread_get_state</strong> function\rreturns the thread's user \rstate, while <strong>thread_set_state</strong> allows modification of the user state.\r<p>\rA problem occurs if a suspended thread had been executing within a system \rcall.  In this case, the thread has, not only a user state, but\ran associated kernel \rstate. (The kernel state cannot be changed with <strong>thread_set_state</strong>.)\rAs a result, \rwhen the thread resumes, the system call can return, producing a change in the \ruser state and, possibly, user memory.\r<p>\rFor a thread executing within a system call, <strong>thread_abort_safely</strong>\raborts the\rkernel call from the thread's point of view.  Specifically, it\rresets the kernel state so \rthat the thread will resume execution at the system call return,\rwith the return \rcode value set to one of the interrupted codes.  The system call itself may\rcompleted entirely, aborted entirely or be partially completed,\rdepending on when \rthe abort is received.  As a result, if the thread's user state\rhas been modified by \r<strong>thread_set_state</strong>, it will not be altered un-predictably\rby any unexpected\rsystem call side effects.\r<p>\rFor example, to simulate a POSIX signal, use the following sequence of calls:\r<dl>\r<dd>\r<strong>thread_suspend</strong>\(emTo stop the thread.\r<dd>\r<strong>thread_abort_safely</strong>\(emTo interrupt any system call in\rprogress and set the \rreturn value to "interrupted".  Because the thread is already stopped, it will \rnot return to user code.\r<dd>\r<strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a\rprocedure call to the signal handler.\r<dd>\r<strong>thread_resume</strong>\(emTo resume execution at the signal handler.\rIf the thread's \rstack is set up correctly, the thread can return to the interrupted\rsystem call. \rNote that the code to push an extra stack frame and change the registers is \rhighly machine dependent.\r</dl>\r<h3>CAUTIONS</h3>\r<p>\rAs a rule, do not use <strong>thread_abort_safely</strong> on a non-suspended\rthread.  This\roperation is very risky because it is difficult to know which\rsystem trap, if any, is \rexecuting and whether an interrupt return will result in some useful action by \rthe thread.\r<p>\r<strong>thread_abort_safely</strong> will not abort any non-atomic operation\r(such as a\rmulti-page <strong>memory_object_data_supply</strong> or exception processing)\rbut will return an \rerror instead.  The caller of this function must then allow the\rthread to resume \rand attempt to abort it later.  If the thread must be aborted,\reven if doing so \rwould abort any non-atomic operations, <strong>thread_abort</strong> would be used.\r<h3>RETURN VALUES</h3>\r<dl>\r<p>\r<dt> <strong>KERN_FAILURE</strong>\r<dd>\rThe thread is in the middle of a non-restartable operation.\r</dl>\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,\r<a href="thread_info.html"><strong>thread_info</strong></a>,\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,\r<a href="thread_abort.html"><strong>thread_abort</strong></a>.\r