<h2>thread_abort</h2> <hr> <p> <strong>Function</strong> - Abort a thread. <h3>SYNOPSIS</h3> <pre> <strong>kern_return_t thread_abort</strong> <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong> </pre> <h3>PARAMETERS</h3> <dl> <p> <dt> <var>target_thread</var> <dd> [in thread send right] The thread to be aborted. </dl> <h3>DESCRIPTION</h3> <p> The <strong>thread_abort</strong> function aborts page faults and any message primitive calls in use by <var>target_thread</var>. Scheduling depressions and clock sleeps are also aborted. The call returns a code indicating that it was interrupted. The call is interrupted even if the thread (or the task containing it) is suspended. If it is suspended, the thread receives the interrupt when it resumes. <p> If its state is not modified before it resumes, the thread will retry an aborted page fault. The Mach message trap returns either <strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending on whether the send or the receive side was interrupted. Note, though, that the Mach message trap is contained within the <strong>mach_msg</strong> library routine, which, by default, retries interrupted message calls. <p> The basic purpose of <strong>thread_abort</strong> is to let one thread cleanly stop another thread (<var>target_thread</var>). The target thread is stopped in such a manner that its future execution can be controlled in a predictable way. When <strong>thread_abort</strong> returns, the target thread will appear to have just returned from the kernel (if it had been in kernel mode). <h3>NOTES</h3> <p> By way of comparison, the <strong>thread_suspend</strong> function keeps the target thread from executing any further instructions at the user level, including the return from a system call. The <strong>thread_get_state</strong> function returns the thread's user state, while <strong>thread_set_state</strong> allows modification of the user state. <p> A problem occurs if a suspended thread had been executing within a system call. In this case, the thread has, not only a user state, but an associated kernel state. (The kernel state cannot be changed with <strong>thread_set_state</strong>.) As a result, when the thread resumes, the system call can return, producing a change in the user state and, possibly, user memory. <p> For a thread executing within a system call, <strong>thread_abort</strong> aborts the kernel call from the thread's point of view. Specifically, it resets the kernel state so that the thread will resume execution at the system call return, with the return code value set to one of the interrupted codes. The system call itself may be completed entirely, aborted entirely or be partially completed, depending on when the abort is received. As a result, if the thread's user state has been modified by <strong>thread_set_state</strong>, it will not be altered un-predictably by any unexpected system call side effects. <p> For example, to simulate a POSIX signal, use the following sequence of calls: <dl> <dd> <strong>thread_suspend</strong>\(emTo stop the thread. <dd> <strong>thread_abort</strong>\(emTo interrupt any system call in progress and set the return value to "interrupted". Because the thread is already stopped, it will not return to user code. <dd> <strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a procedure call to the signal handler. <dd> <strong>thread_resume</strong>\(emTo resume execution at the signal handler. If the thread's stack is set up correctly, the thread can return to the interrupted system call. Note that the code to push an extra stack frame and change the registers is highly machine dependent. </dl> <h3>CAUTIONS</h3> <p> As a rule, do not use <strong>thread_abort</strong> on a non-suspended thread. This operation is very risky because it is difficult to know which system trap, if any, is executing and whether an interrupt return will result in some useful action by the thread. <p> <strong>thread_abort</strong> will abort any non-atomic operation (such as a multi-page <strong>memory_object_data_supply</strong>) at an arbitrary point in a non-restartable way. Such problems can be avoided by using <strong>thread_abort_safely</strong>. <h3>RETURN VALUES</h3> <dl> <p> <dt> <strong>KERN_EXCEPTION_PROTECTED</strong> <dd> The thread is processing a protected exception. </dl> <h3>RELATED INFORMATION</h3> <p> Functions: <a href="mach_msg.html"><strong>mach_msg</strong></a>, <a href="thread_get_state.html"><strong>thread_get_state</strong></a>, <a href="thread_info.html"><strong>thread_info</strong></a>, <a href="thread_set_state.html"><strong>thread_set_state</strong></a>, <a href="thread_suspend.html"><strong>thread_suspend</strong></a>, <a href="thread_terminate.html"><strong>thread_terminate</strong></a>, <a href="thread_abort_safely.html"><strong>thread_abort_safely</strong></a>, <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>.