-<h2>thread_abort_safely</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Abort a thread, restartably.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_abort_safely</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_safely</strong> function aborts page faults and any message
\rprimitive calls in use by <var>target_thread</var>. Scheduling depressions
\rand clock sleeps are
\ralso aborted. The call returns a code indicating that it was
\rinterrupted. The call
\ris interrupted even if the thread (or the task containing it)
\ris suspended. 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_safely</strong> is to let
\rone thread cleanly stop
\ranother thread (<var>target_thread</var>). The target thread is stopped
\rin such a manner that
\rits future execution can be controlled in a predictable way. When
\r<strong>thread_abort_safely</strong> returns (if successful), the target
\rthread will appear to have just
\rreturned from the kernel (if it had 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_safely</strong>
\raborts the
\rkernel call from the thread's point of view. Specifically, it
\rresets the kernel state so
\rthat the thread will resume execution at the system call return,
\rwith the return
\rcode value set to one of the interrupted codes. The system call itself may
\rcompleted entirely, aborted entirely or be partially completed,
\rdepending on when
\rthe abort is received. As a result, if the thread's user state
\rhas been 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_safely</strong>\(emTo interrupt any system call in
\rprogress and set the
\rreturn value to "interrupted". Because the thread is already stopped, it will
\rnot return 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
\rsystem 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_safely</strong> on a non-suspended
\rthread. This
\roperation is very risky because it is difficult to know which
\rsystem trap, if any, is
\rexecuting and whether an interrupt return will result in some useful action by
\rthe thread.
\r<p>
\r<strong>thread_abort_safely</strong> will not abort any non-atomic operation
\r(such as a
\rmulti-page <strong>memory_object_data_supply</strong> or exception processing)
\rbut will return an
\rerror instead. The caller of this function must then allow the
\rthread to resume
\rand attempt to abort it later. If the thread must be aborted,
\reven if doing so
\rwould abort any non-atomic operations, <strong>thread_abort</strong> would be used.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe thread is in the middle of a non-restartable operation.
\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.html"><strong>thread_abort</strong></a>.
\r\ No newline at end of file
+<h2>thread_abort_safely</h2>
+<hr>
+<p>
+<strong>Function</strong> - Abort a thread, restartably.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_abort_safely</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_safely</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_safely</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_safely</strong> returns (if successful), 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_safely</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
+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_safely</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_safely</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_safely</strong> will not abort any non-atomic operation
+(such as a
+multi-page <strong>memory_object_data_supply</strong> or exception processing)
+but will return an
+error instead. The caller of this function must then allow the
+thread to resume
+and attempt to abort it later. If the thread must be aborted,
+even if doing so
+would abort any non-atomic operations, <strong>thread_abort</strong> would be used.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The thread is in the middle of a non-restartable operation.
+</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.html"><strong>thread_abort</strong></a>.
projects / apple / xnu.git / blobdiff