1<h2>thread_abort</h2> 2<hr> 3<p> 4<strong>Function</strong> - Abort a thread. 5<h3>SYNOPSIS</h3> 6<pre> 7<strong>kern_return_t thread_abort</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</strong> function aborts page faults and any 21message primitive calls 22in use by <var>target_thread</var>. Scheduling depressions and clock sleeps are also 23aborted. The call returns a code indicating that it was interrupted. 24The call is 25interrupted even if the thread (or the task containing it) is 26suspended. 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</strong> is to let one thread 40cleanly stop another thread (<var>target_thread</var>). 41The target thread is stopped in such a manner that its 42future execution can be controlled in a predictable way. When 43<strong>thread_abort</strong> 44returns, the target thread will appear to have just returned 45from the kernel (if it 46had 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</strong> 66aborts the kernel call 67from the thread's point of view. Specifically, it resets the 68kernel state so that the 69thread will resume execution at the system call return, with the return code 70value set to one of the interrupted codes. The system call itself 71may be completed 72entirely, aborted entirely or be partially completed, depending on when the 73abort is received. As a result, if the thread's user state has 74been modified by 75<strong>thread_set_state</strong>, it will not be altered un-predictably 76by any unexpected 77system call side effects. 78<p> 79For example, to simulate a POSIX signal, use the following sequence of calls: 80<dl> 81<dd> 82<strong>thread_suspend</strong>\(emTo stop the thread. 83<dd> 84<strong>thread_abort</strong>\(emTo interrupt any system call in progress 85and set the return 86value to "interrupted". Because the thread is already stopped, it will not 87return to user code. 88<dd> 89<strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a 90procedure call to the signal handler. 91<dd> 92<strong>thread_resume</strong>\(emTo resume execution at the signal handler. 93If the thread's 94stack is set up correctly, the thread can return to the interrupted system call. 95Note that the code to push an extra stack frame and change the registers is 96highly machine dependent. 97</dl> 98<h3>CAUTIONS</h3> 99<p> 100As a rule, do not use <strong>thread_abort</strong> on a non-suspended 101thread. This operation 102is very risky because it is difficult to know which system trap, if any, is 103executing and whether an interrupt return will result in some 104useful action by the 105thread. 106<p> 107<strong>thread_abort</strong> will abort any non-atomic operation (such as a multi-page 108<strong>memory_object_data_supply</strong>) at an arbitrary point in a non-restartable 109way. Such problems can be avoided by using <strong>thread_abort_safely</strong>. 110<h3>RETURN VALUES</h3> 111<dl> 112<p> 113<dt> <strong>KERN_EXCEPTION_PROTECTED</strong> 114<dd> 115The thread is processing a protected exception. 116</dl> 117<h3>RELATED INFORMATION</h3> 118<p> 119Functions: 120<a href="mach_msg.html"><strong>mach_msg</strong></a>, 121<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, 122<a href="thread_info.html"><strong>thread_info</strong></a>, 123<a href="thread_set_state.html"><strong>thread_set_state</strong></a>, 124<a href="thread_suspend.html"><strong>thread_suspend</strong></a>, 125<a href="thread_terminate.html"><strong>thread_terminate</strong></a>, 126<a href="thread_abort_safely.html"><strong>thread_abort_safely</strong></a>, 127<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>. 128