thread_abort


Function - Abort a thread.

SYNOPSIS

kern_return_t   thread_abort
                (thread_act_t                     target_thread);

PARAMETERS

target_thread
[in thread send right] The thread to be aborted.

DESCRIPTION

The thread_abort function aborts page faults and any message primitive calls in use by target_thread. 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.

If its state is not modified before it resumes, the thread will retry an aborted page fault. The Mach message trap returns either MACH_SEND_INTERRUPTED or MACH_RCV_INTERRUPTED, depending on whether the send or the receive side was interrupted. Note, though, that the Mach message trap is contained within the mach_msg library routine, which, by default, retries interrupted message calls.

The basic purpose of thread_abort is to let one thread cleanly stop another thread (target_thread). The target thread is stopped in such a manner that its future execution can be controlled in a predictable way. When thread_abort returns, the target thread will appear to have just returned from the kernel (if it had been in kernel mode).

NOTES

By way of comparison, the thread_suspend function keeps the target thread from executing any further instructions at the user level, including the return from a system call. The thread_get_state function returns the thread's user state, while thread_set_state allows modification of the user state.

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 thread_set_state.) As a result, when the thread resumes, the system call can return, producing a change in the user state and, possibly, user memory.

For a thread executing within a system call, thread_abort 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 thread_set_state, it will not be altered un-predictably by any unexpected system call side effects.

For example, to simulate a POSIX signal, use the following sequence of calls:

thread_suspend\(emTo stop the thread.
thread_abort\(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.
thread_set_state\(emTo modify the thread's user state to simulate a procedure call to the signal handler.
thread_resume\(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.

CAUTIONS

As a rule, do not use thread_abort 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.

thread_abort will abort any non-atomic operation (such as a multi-page memory_object_data_supply) at an arbitrary point in a non-restartable way. Such problems can be avoided by using thread_abort_safely.

RETURN VALUES

KERN_EXCEPTION_PROTECTED
The thread is processing a protected exception.

RELATED INFORMATION

Functions: mach_msg, thread_get_state, thread_info, thread_set_state, thread_suspend, thread_terminate, thread_abort_safely, thread_set_exception_ports.