thread_terminate(9r)													      thread_terminate(9r)

NAME

       thread_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
       previous call to the kernel_isrthread or kernel_thread_w_arg routine.

DESCRIPTION

       The thread_terminate routine prepares to stop or permanently stops execution of the specified kernel thread. You created and  started  this
       kernel  thread  in  a  previous	call to the kernel_isrthread or kernel_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 terminating 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 ker-
	      nel_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 execution 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 kernel_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  config-
       ured  kernel module uses kernel threads, you should terminate them in the CFG_OP_UNCONFIGURE entry point of the loadable module's configure
       routine.  The kernel threads are no longer needed after the module is unconfigured.

       Note that the thread_terminate routine (for kernel threads that terminate 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_terminate 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)