pthread_num_ldoms_np man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

pthread_processor_bind_np(3T)			 pthread_processor_bind_np(3T)

NAME
       pthread_processor_bind_np(),  pthread_num_processors_np(), pthread_pro‐
       cessor_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  available,
       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 bind‐
       ing

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 proces‐
       sors.  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 numer‐
       ical  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  proces‐
       sors  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, mem‐
       ory, 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 local‐
       ity 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 pro‐
		     cessor 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 argu‐
		     ment 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	deter‐
		     mine the IDs of the remaining ldoms.

       The  function returns the ID of the locality domain containing the pro‐
       cessor 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 speci‐
       fied 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 assign‐
		     ment and allow the implementation to choose which proces‐
		     sor  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   scheduling  policy  shall  overrule	the  processor
		     assignment. 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  proces‐
		     sor,  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 proces‐
		     sor 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, cooperating
       threads should not rely on locality domain assignment in lieu of a syn‐
       chronization 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 local‐
       ity 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 processor  will
       choose  a lower priority thread to execute instead of completely honor‐
       ing 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 correspond‐
       ing 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 bind‐
			     ing 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)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net