-<h2>thread_abort</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Abort a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_abort</strong>
\r <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_thread</var>
\r<dd>
\r[in thread send right]
\rThe thread to be aborted.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_abort</strong> function aborts page faults and any
\rmessage primitive calls
\rin use by <var>target_thread</var>. Scheduling depressions and clock sleeps are also
\raborted. The call returns a code indicating that it was interrupted.
\rThe call is
\rinterrupted even if the thread (or the task containing it) is
\rsuspended. If it is
\rsuspended, the thread receives the interrupt when it resumes.
\r<p>
\rIf its state is not modified before it resumes, the thread will
\rretry an aborted
\rpage fault. The Mach message trap returns either
\r<strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending
\ron whether the send or the
\rreceive side was interrupted. Note, though, that the Mach message trap is
\rcontained within the <strong>mach_msg</strong> library routine, which,
\rby default, retries
\rinterrupted message calls.
\r<p>
\rThe basic purpose of <strong>thread_abort</strong> is to let one thread
\rcleanly stop another thread (<var>target_thread</var>).
\rThe target thread is stopped in such a manner that its
\rfuture execution can be controlled in a predictable way. When
\r<strong>thread_abort</strong>
\rreturns, the target thread will appear to have just returned
\rfrom the kernel (if it
\rhad been in kernel mode).
\r<h3>NOTES</h3>
\r<p>
\rBy way of comparison, the <strong>thread_suspend</strong> function keeps
\rthe target thread
\rfrom executing any further instructions at the user level, including
\rthe return
\rfrom a system call. The <strong>thread_get_state</strong> function
\rreturns the thread's user
\rstate, while <strong>thread_set_state</strong> allows modification of the user state.
\r<p>
\rA problem occurs if a suspended thread had been executing within a system
\rcall. In this case, the thread has, not only a user state, but
\ran associated kernel
\rstate. (The kernel state cannot be changed with <strong>thread_set_state</strong>.)
\rAs a result,
\rwhen the thread resumes, the system call can return, producing a change in the
\ruser state and, possibly, user memory.
\r<p>
\rFor a thread executing within a system call, <strong>thread_abort</strong>
\raborts the kernel call
\rfrom the thread's point of view. Specifically, it resets the
\rkernel state so that the
\rthread will resume execution at the system call return, with the return code
\rvalue set to one of the interrupted codes. The system call itself
\rmay be completed
\rentirely, aborted entirely or be partially completed, depending on when the
\rabort is received. As a result, if the thread's user state has
\rbeen modified by
\r<strong>thread_set_state</strong>, it will not be altered un-predictably
\rby any unexpected
\rsystem call side effects.
\r<p>
\rFor example, to simulate a POSIX signal, use the following sequence of calls:
\r<dl>
\r<dd>
\r<strong>thread_suspend</strong>\(emTo stop the thread.
\r<dd>
\r<strong>thread_abort</strong>\(emTo interrupt any system call in progress
\rand set the return
\rvalue to "interrupted". Because the thread is already stopped, it will not
\rreturn to user code.
\r<dd>
\r<strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a
\rprocedure call to the signal handler.
\r<dd>
\r<strong>thread_resume</strong>\(emTo resume execution at the signal handler.
\rIf the thread's
\rstack is set up correctly, the thread can return to the interrupted system call.
\rNote that the code to push an extra stack frame and change the registers is
\rhighly machine dependent.
\r</dl>
\r<h3>CAUTIONS</h3>
\r<p>
\rAs a rule, do not use <strong>thread_abort</strong> on a non-suspended
\rthread. This operation
\ris very risky because it is difficult to know which system trap, if any, is
\rexecuting and whether an interrupt return will result in some
\ruseful action by the
\rthread.
\r<p>
\r<strong>thread_abort</strong> will abort any non-atomic operation (such as a multi-page
\r<strong>memory_object_data_supply</strong>) at an arbitrary point in a non-restartable
\rway. Such problems can be avoided by using <strong>thread_abort_safely</strong>.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
\r<dd>
\rThe thread is processing a protected exception.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
\r<a href="thread_abort_safely.html"><strong>thread_abort_safely</strong></a>,
\r<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>.
\r\ No newline at end of file
+<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>.
projects / apple / xnu.git / blobdiff