Index Index for
Section 9r
Index Alphabetical
listing for T
Bottom of page Bottom of
page		 

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

  thread_to_terminate
      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 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

  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

  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)

Index Index for
Section 9r
Index Alphabetical
listing for T
Top of page Top of
page