pthread_processor_bind_np(3T)											     pthread_processor_bind_np(3T)

NAME

       pthread_processor_bind_np(),  pthread_num_processors_np(),  pthread_processor_id_np(),  pthread_num_ldoms_np(), pthread_num_ldomprocs_np(),
       pthread_spu_to_ldom_np(), pthread_ldom_bind_np(), pthread_ldom_id_np(), pthread_pset_bind_np() - determine how many processors  are  avail-
       able,  bind threads to processors, and determine processor IDs; determine how many locality domains are available, bind threads to locality
       domains, and determine locality domain IDs; change thread's processor set binding

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.

	      spu	This parameter gives the value of the spu for certain requests.

	      ldom	This parameter gives the value of the locality domain for certain requests.

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

	      pset	This parameter gives the value of the processor set for certain requests.

REMARKS

       Much of the functionality of this capability is highly dependent on the underlying hardware.  An  application  that  uses  these  functions
       should not be expected to be portable across architectures or implementations.

       Some hardware platforms support online addition and deletion of processors.  Due to this capability, processors and locality domains may be
       added or deleted while the system is running. Applications should be written to handle processor IDs and locality domain IDs  that  dynami-
       cally appear or disappear (for example, sometime after obtaining the IDs of all the processors in the system an application may try to bind
       a thread to one of those processors - these functions will return an error if that processor had been deleted).

       Processor and locality domain IDs are not guaranteed to exist in numerical order.  There may be holes in a sequential list of IDs.  Due	to
       the capability of online addition and deletion of processors on some platforms, processor and locality domain IDs obtained via these inter-
       faces may be invalid at a later time.  Likewise, the number of processors and locality domains in the system may also change due to proces-
       sors being added or deleted.

       Processor  sets restrict application execution to a designated group of processors. These functions return information about processors and
       locality domains available to the calling application.  Refer to mpctl(2) for system-wide topology information.

DESCRIPTION

       These functions provide a means of determining how many processors and locality domains are available to  the  applications  and  assigning
       threads to run on specific processors or locality domains.

       A  locality  domain  consists  of a related collection of processors, memory, and peripheral resources that comprise a fundamental building
       block of the system. All processors and peripheral devices in a given locality domain have equal latency to  the  memory  contained  within
       that locality domain.

       Processor  sets	furnish an alternative application scheduling allocation domain. A processor set comprises an isolated group of processors
       for exclusive use by applications assigned to the processor set. (See pset_create(2) for details). Use with name to see	if  the  processor
       set functionality is enabled and available on the system.

   Topology Information
       The function returns the number of processors in the processor set of the calling thread.

       The function returns the number of locality domains in the processor set of the calling thread.

       The function returns the number of processors contributed by the locality domain ldom to the processor set of the calling thread. It may be
       less than the total number of processors in the ldom.  The number of processors is returned in the answer parameter.

       The function obtains the processor ID of a specific processor on the system. The processor ID is returned in answer.  The request parameter
       determines the precise action to be taken and is one of the following:

	      This request stores in the
		     answer parameter the ID of the first processor in the processor set of the calling thread. The spu argument is ignored.

	      This request stores in the
		     answer parameter the ID of the next processor in the processor set of the calling thread after spu.

		     Typically,  is  called  to determine the first spu.  is then called in a loop (until the call returns to determine the IDs of
		     the remaining spus.

	      This request stores in the
		     answer parameter the ID of the processor the thread is currently running on. The spu argument is ignored.	Note: This  option
		     returns the current processor on which the caller is executing, NOT the processor assignment of the caller.

		     This  information	may  be  out-of-date  arbitrarily soon after the call completes due to the scheduler context switching the
		     caller onto another processor.

       The function obtains the locality domain ID of a specific locality domain on the system. The locality domain ID is returned in answer.  The
       request parameter determines the precise action to be taken and is one of the following:

	      This request stores in the
		     answer  parameter	the  ID  of  the  first  locality  domain in the processor set of the calling thread. The ldom argument is
		     ignored.

	      This request stores in the
		     answer parameter the ID of the next locality domain in the processor set of the calling thread after ldom.

		     Typically, is called to determine the first ldom.	is then called in a loop (until the call returns to determine the  IDs	of
		     the remaining ldoms.

       The function returns the ID of the locality domain containing the processor specified by spu.  The locality domain ID is returned in ldom.

   Processor Set Binding
       All  threads  have binding or association to a processor set, and they execute on processors within that set.  The function allows a thread
       to change its binding to another processor set.	The thread needs EXEC permission to bind to another processor set  (See  pset_bind(2)  for
       details). The thread's contention scope must be to change a thread's processor set binding.

       The thread specified by tid is the target thread whose binding is changed. The pset parameter specifies the new processor set for tid.  The
       new processor set for the thread is returned in answer.

       The tid can be used to refer to the calling thread. The pset can be used to read the current processor set assignment for the thread.

   Processor Binding
       Processor binding is expected to be used to increase performance in certain applications to prevent cache thrashing or to cause threads	to
       execute	in  parallel  on  different  processors.  It should not be used to ensure correctness of an application. Specifically, cooperating
       threads should not rely on processor assignment in lieu of a synchronization mechanism (such as mutexes).

       Processor binding and locality domain binding is mutually exclusive - only one can be in effect at any time. If locality domain binding	is
       in effect, the target is allowed to execute on any processor within that locality domain.

       Due  to the capability of online addition and deletion of processors on some platforms, processors may go away. If this occurs, any threads
       bound to a departing processor will be rebound to a different processor with the same binding type.

       The function binds a thread to a specific processor.  The thread specified by tid is the target thread whose binding is changed.   The  spu
       parameter  specifies  the new processor binding for tid.  The request parameter determines the precise action to be taken and is one of the
       following:

	      This call is
		     advisory.	This request assigns thread tid to processor spu.  The new processor assignment is returned in answer.

		     The tid can be used to refer to the calling thread.

		     The spu may be passed to read the current assignment. The spu may be used to break  any  specific	processor  assignment  and
		     allow  the implementation to choose which processor the thread should execute on when it is scheduled to execute. This allows
		     the thread to run on any processor the implementation chooses.

		     This request is only advisory. If the scheduling policy for the thread conflicts with this processor assignment, the schedul-
		     ing  policy  shall overrule the processor assignment. For example, when a processor is ready to choose another thread to exe-
		     cute, if the highest priority thread on the run queue is bound to a different processor, that  thread  will  execute  on  the
		     available processor rather than waiting for the processor to which it is bound.

	      This request is identical to
		     except  that this thread to processor binding will over rule the scheduling policy. For example, when a processor is ready to
		     choose another thread to execute, if the highest priority thread on the run queue is bound to  a  different  processor,  that
		     thread will not be chosen by the available processor. That thread will wait until the wanted processor becomes available. The
		     available processor will choose a lower priority thread to execute instead of completely honoring the scheduling policies.

       Note: binding a thread to a specific processor essentially changes the scheduling allocation domain size for that thread to be one.  Having
       a  thread  float  and  be  scheduled  on whatever processor the system chooses sets a thread's scheduling allocation domain size to a value
       greater than one (it will generally be equal to the number of processors on the system).

   Locality Domain Binding
       Locality domain binding is expected to be used to increase performance in certain applications to  prevent  cache  thrashing  or  to  cause
       threads	to execute in parallel on different processors. It should not be used to ensure correctness of an application. Specifically, coop-
       erating threads should not rely on locality domain assignment in lieu of a synchronization mechanism (such as mutexes).

       Processor binding and locality domain binding is mutually exclusive - only one can be in effect at any time. If locality domain binding	is
       in effect, the target is allowed to execute on any processor within that locality domain.

       Due  to the capability of online addition and deletion of processors on some platforms, locality domains may go away. If the last processor
       in a locality domain is removed, any threads bound to a departing locality domain will be rebound to a different locality domain.

       The function binds a thread to a specific locality domain.  The new locality domain binding is returned in answer.

       The thread specified by tid is the target thread whose binding is changed.  The value can be used to refer to the calling thread.

       The ldom parameter specifies the new locality domain binding for tid.  The value may be passed to only read the	current  assignment.   The
       value  may  be  passed  to  break  any specific locality domain assignment and allow the implementation to choose which locality domain the
       thread should execute in.  This allows the thread to run on any processor the implementation chooses.  Otherwise, ldom specifies the ID	of
       the locality domain to which tid should be bound to.

       The  locality  domain  binding  will  take  precedence over the scheduling policy. For example, when a processor is ready to choose another
       thread to execute, if the highest priority thread on the run queue is bound to a different locality domain, that thread will not be  chosen
       by  the available processor. That thread will wait until a processor in the wanted locality domain becomes available. The available proces-
       sor will choose a lower priority thread to execute instead of completely honoring the scheduling policies.

RETURN VALUE

       always returns the number of processors on the system.  It never fails.

       always returns the number of locality domains on the system.  It never fails.

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

       Note: In some cases, and may return a negative value, other than -1, in the field which still indicates	a  successful  return.	 Refer	to
       mpctl(2) for the definition of the returned value.

ERRORS

       If any of the following occur, the and functions return the corresponding error number:

	      The	     request parameter contains an illegal value.

	      The	     spu or ldom parameter contains an invalid ID.

	      The	     request parameter is and spu identifies the last processor.

	      The	     request parameter is and ldom identifies the last locality domain.

	      The value specified by
			     answer is illegal.

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

	      request	     is  or  spu  is not and the caller does not have the appropriate permission to change a threads binding to a specific
			     processor.

	      The function is
			     and thread tid does not have necessary permission to bind to the pset.

AUTHOR

       and were developed by HP.

SEE ALSO

       sleep(3C), rtsched(2), mpctl(2), pset_create(2), pset_bind(2), sysconf(2).

STANDARDS CONFORMANCE

								  Pthread Library				     pthread_processor_bind_np(3T)