pthread_launch_policy_np(3T)											      pthread_launch_policy_np(3T)

NAME

       pthread_launch_policy_np() - setting thread launch policies

SYNOPSIS

PARAMETERS

	      request	This parameter determines the precise action to be taken by these functions.

	      answer	This parameter is an output parameter in which values are returned. The meaning of answer depends on request parameter.

	      tid	This parameter gives the value of the thread id for certain requests.

DESCRIPTION

       Each  process  shall  have a launch policy.  Each thread shall have a launch policy.  The launch policy for a thread does not have to match
       the launch policy for the process.  The launch policy determines the locality domain where the newly created  process  or  thread  will	be
       launched in a ccNUMA system.  The locality domains covered by a process's or thread's processor set are the available locality domains.

       The  function  sets  a thread launch policy for a specific thread.  The thread specified by tid is the target thread whose launch policy is
       changed.  The value can be used to refer to the calling thread.

       is currently not supported for threads. If is used on a thread, it is silently ignored and zero is returned for successful completion.

       When a process creates another process (via or the child process will inherit the parent process's launch policy.  The  initial	thread	in
       the  child  process will inherit the launch policy of the creating thread (and not that of its process).  Other threads in a multi-threaded
       process inherit their launch policy from the creating thread.

       For all launch policies, the target thread is bound to the locality domain on which it was launched.  The target is allowed to  execute	on
       any processor within that locality domain.

       When setting a launch policy, if the target already has processor or locality domain binding, the existing binding will not be overwritten.
       Instead the locality domain in which the target is bound (whether locality domain binding or processor binding) will be used as the  start-
       ing locality domain for implementing the launch policy.

       Refer to mpctl(2) man page for further details on launch policies.

       Note:  locality	domains  are tightly tied to the physical components of the underlying system.	As a result, the performance observed when
       using launch policies based on locality domains may vary from system to system.	For example, a system which contains 4	locality  domains,
       each  containing  32 processors, may exhibit different performance behaviors from a system that contains 32 locality domains with 4 proces-
       sors per domain. The launch policy that provides optimal performance on one system may not provide optimal performance on a different  sys-
       tem for the same application.

       The request parameter specifies the action to take and may be one of the following:

	      The current launch policy of the target thread is returned in the
		     answer  parameter.   This	request currently returns or to indicate the current launch policy of the thread specified by tid.
		     Other launch policies may be added in future releases and returned via this option.  Applications using this option should be
		     written to handle other return values in order to continue working on future releases.

	      This request establishes a round robin launch policy
		     for  the  specified  thread.   The  successive  child  threads of the specified thread will be launched on different locality
		     domains in a round robin manner until all available locality domains have been used by threads in the launch tree.   At  that
		     point, the selection of locality domains begins again from the original locality domain.  The answer parameter is ignored.

	      This request establishes a fill first launch policy
		     for  the specified thread.  The successive child threads of the specified thread will be launched on the same locality domain
		     as their parent thread until one thread has been created for each available processor in the domain.  At that  point,  a  new
		     locality domain is selected and successive threads are launched there until there is one thread per processor.  All available
		     locality domains will be used before the original domain is selected again.  The answer parameter is ignored.

	      This request establishes a packed launch policy
		     for the specified thread.	The successive child threads are launched on the same locality domain as their parent thread.  The
		     answer parameter is ignored.

	      This request establishes a least loaded launch policy
		     for the specified thread.	The successive child threads are launched on the least loaded locality domain in the processor set
		     regardless of the location of their parent thread.  The answer parameter is ignored.

	      This request establishes a tree based round robin launch policy
		     for the specified thread.	This request differs from in which threads become part of the launch  tree.   This  launch  policy
		     includes all descendents of the target thread in the launch tree.	The answer parameter is ignored.

	      This request establishes a tree based fill first launch policy
		     for  the  specified  thread.   This request differs from in which threads become part of the launch tree.	This launch policy
		     includes all descendents of the target thread in the launch tree.	The answer parameter is ignored.

	      This request unsets any launch policy in the thread.  The system will employ
		     a default, optimal policy in determining where the newly created thread will be launched.	The existing binding of the thread
		     is not changed.  The answer parameter is ignored.

RETURN VALUE

       Upon successful completion, returns zero.  Otherwise, an error number is returned to indicate the error (the variable is not set).

ERRORS

       If any of the following occur, the function returns the corresponding error number:

	      [EINVAL]	     The request parameter contains an illegal value.

	      [EINVAL]	     The value specified by answer is illegal.

	      [ESRCH]	     No thread could be found in the current process that matches the thread ID specified in tid.

WARNINGS

       is  currently  not supported for threads. If is used on a thread, it is silently ignored and zero is returned for successful completion. If
       the request parameter is answer is set to For all other request values, answer parameter is ignored. Applications dependent on the complete
       implementation of should use threads.

AUTHOR

       was developed by HP.

SEE ALSO

       mpctl(2), sleep(3C), rtsched(2).

STANDARDS CONFORMANCE

								  Pthread Library				      pthread_launch_policy_np(3T)