Function - Abort a thread, restartably.
kern_return_t thread_abort_safely
(thread_act_t target_thread);
The thread_abort_safely 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_safely 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_safely returns (if successful), the target thread will appear to have just returned from the kernel (if it had been in kernel mode).
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_safely 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 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:
As a rule, do not use thread_abort_safely 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_safely will not abort any non-atomic operation (such as a multi-page memory_object_data_supply 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, thread_abort would be used.
Functions: mach_msg, thread_get_state, thread_info, thread_set_state, thread_suspend, thread_terminate, thread_abort.