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