NAME    [Toc]    [Back]

       thread_terminate - General: Prepares to stop or stops execution
 of the specified kernel thread

SYNOPSIS    [Toc]    [Back]

       kern_return_t thread_terminate(
               thread_t thread_to_terminate );

ARGUMENTS    [Toc]    [Back]

       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    [Toc]    [Back]

       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    terminates   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 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 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    [Toc]    [Back]

       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 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    [Toc]    [Back]

       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    [Toc]    [Back]

       Data Structures: thread(9s)

       Routines:  kernel_isrthread(9r),  kernel_thread_w_arg(9r),
       thread_halt_self(9r)



                                             thread_terminate(9r)