thread_terminate(9r)thread_terminate(9r)NAMEthread_terminate - General: Prepares to stop or stops execution of the
specified kernel thread
SYNOPSIS
kern_return_t thread_terminate(
thread_t thread_to_terminate );
ARGUMENTS
Specifies a pointer to the thread structure associated with the kernel
thread that you want to terminate. This pointer was returned in a pre‐
vious call to the kernel_isrthread or kernel_thread_w_arg routine.
DESCRIPTION
The thread_terminate routine prepares to stop or permanently stops exe‐
cution of the specified kernel thread. You created and started this
kernel thread in a previous call to the kernel_isrthread or ker‐
nel_thread_w_arg routine. These routines return a pointer to the thread
structure associated with the newly created and started kernel thread.
Kernel modules use this pointer as a handle to identify the specific
kernel thread that thread_terminate stops executing.
Typically, a kernel thread terminates itself. However, one kernel
thread can terminate another kernel thread. A kernel thread that termi‐
nates itself must call thread_halt_self immediately after the call to
thread_terminate. The reason for this is that thread_terminate only
prepares the self-terminating kernel thread to stop execution. The
thread_halt_self routine completes the work needed to stop execution
(by performing the appropriate cleanup work) of the self-terminating
kernel thread.
Specifically, the thread_terminate routine works as follows: For termi‐
nating other kernel threads
The thread_terminate routine stops execution of the specified
kernel thread, frees any resources associated with that kernel
thread, and thus makes the kernel thread unavailable. To make
the kernel thread available again, you need to create it by
calling kernel_isrthread or kernel_thread_w_arg. A kernel
thread terminates itself
The thread_terminate routine prepares to stop execution of the
kernel thread that needs to terminate itself. The
thread_halt_self routine completes the work needed to stop exe‐
cution of the self-terminating kernel thread by performing the
appropriate cleanup work. After you call these routines, the
self-terminating kernel thread becomes unavailable until you
create it again by calling kernel_isrthread or ker‐
nel_thread_w_arg.
NOTES
You do not need to terminate every kernel thread that you create. You
should not terminate a kernel thread that is waiting for some event.
The basic rule is that you should terminate only those kernel threads
that you do not need anymore. For example, if a dynamically configured
kernel module uses kernel threads, you should terminate them in the
CFG_OP_UNCONFIGURE entry point of the loadable module's configure rou‐
tine. The kernel threads are no longer needed after the module is
unconfigured.
Note that the thread_terminate routine (for kernel threads that termi‐
nate other kernel threads) not only permanently stops execution of the
specified kernel thread, but it also frees any resources associated
with that kernel thread; thus, this kernel thread can no longer be
used.
RETURN VALUES
Upon successfully terminating the specified kernel thread, thread_ter‐
minate returns the constant KERN_SUCCESS. If the thread structure
pointer passed to the thread_to_terminate argument does not identify a
valid kernel thread, thread_terminate returns the constant
KERN_INVALID_ARGUMENT. On any other error, thread_terminate returns
the constant KERN_FAILURE.
SEE ALSO
Data Structures: thread(9s)
Routines: kernel_isrthread(9r), kernel_thread_w_arg(9r),
thread_halt_self(9r)thread_terminate(9r)