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