xnu-2422.1.72.tar.gz

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

<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>.