NAME
thread_abort - interrupts the specified thread

SYNOPSIS
#include <mach.h>

kern_return_t thread_abort(target_thread)
thread_t target_thread;

ARGUMENTS
target_thread The thread to be interrupted.

DESCRIPTION
thread_abort aborts the kernel primitives: msg_send, msg_receive
and msg_rpc and page-faults, making the call return a code
indicating that it was interrupted. The call is interrupted
whether or not the thread (or task containing it) is currently
suspended. If it is supsended, the thread receives the interupt
when it is resumed.

A thread will retry an aborted page-fault if its state is not
modified before it is resumed. Msg_send returns SEND_INTERRUPTED;
msg_receive returns RCV_INTERRUPTED; msg_rpc returns either
SEND_INTERRUPTED or RCV_INTERRUPTED, depending on which half of the
RPC was interrupted.

The main reason for this primitive is to allow one thread to
cleanly stop another thread in a manner that will allow the future
execution of the target thread to be controlled in a predictable
way. thread_suspend keeps the target thread from executing any
further instructions at the user level, including the return from a
system call. thread_get/set_state allows the examination or
modification of the user state of a target thread. However, if a
suspended thread was executing within a system call, it also has
associated with it a kernel state. This kernel state can not be
modified by thread_set_state with the result that when the thread
is resumed the system call may return changing the user state and
possibly user memory. thread_abort aborts the kernel call from the
target thread’s point of view by resetting 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 will either be entirely completed or entirely aborted,
depending on the precise moment at which the abort was received.
Thus if the thread’s user state has been changed by
thread_set_state, it will not be modified by any unexpected system
call side effects.

For example to simulate a Unix signal, the following sequence of
calls may be used:

thread_suspend Stops the thread

thread_abort Interrupts any system call in progress, setting the
return value to ’interrupted’. Since the thread is
stopped, it will not return to user code.

thread_set_state
Alters thread’s state to simulate a procedure call
to the signal handler

thread_resume Resumes execution at the signal handler. If the
thread’s stack has been correctly set up, the thread
may return to the interrupted system call.

(Of course, the code to push an extra stack frame and change the
registers is VERY machine-dependent.)

Calling thread_abort on a non-suspended thread is pretty risky,
since it is very difficult to know exactly what system trap, if
any, the thread might be executing and whether an interrupt return
would cause the thread to do something useful.

DIAGNOSTICS
KERN_SUCCESS The thread received an interrupt

KERN_INVALID_ARGUMENT target_thread is not a thread.

SEE ALSO
thread_info(2), thread_state(2), thread_terminate(2),
thread_suspend(2)