pthread_processor_bind

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

SYNOPSIS

#include <pthread.h>

int pthread_num_processors_np(void);

int pthread_num_ldoms_np(void);

int pthread_num_ldomprocs_np( 
   int *answer,  
   pthread_ldom_t ldom 
); 

int pthread_processor_id_np( 
   int request, 
   pthread_spu_t *answer, 
   pthread_spu_t spu 
); 

int pthread_ldom_id_np( 
   int request, 
   pthread_ldom_t *answer, 
   pthread_ldom_t ldom 
); 

int pthread_spu_to_ldom_np( 
   pthread_spu_t spu, 
   pthread_ldom_t *ldom 
); 

int pthread_processor_bind_np( 
   int request, 
   pthread_spu_t *answer, 
   pthread_spu_t spu, 
   pthread_t tid 
); 

int pthread_ldom_bind_np( 
   pthread_ldom_t *answer, 
   pthread_ldom_t ldom, 
   pthread_t tid 
); 

int pthread_pset_bind_np( 
   psetid_t *answer, 
   psetid_t pset, 
   pthread_t tid 
); 

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 dynamically 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 interfaces may be invalid at a later time. Likewise, the number of processors and locality domains in the system may also change due to processors 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 sysconf() with _SC_PSET_SUPPORT name to see if the processor set functionality is enabled and available on the system.

Topology Information

The pthread_num_processors_np() function returns the number of processors in the processor set of the calling thread.

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

The pthread_num_ldomprocs_np() 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 pthread_processor_id_np() 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:

PTHREAD_GETFIRSTSPU_NP

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.

PTHREAD_GETNEXTSPU_NP

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

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

PTHREAD_GETCURRENTSPU_NP

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 pthread_ldom_id_np() 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:

PTHREAD_GETFIRSTLDOM_NP

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.

PTHREAD_GETNEXTLDOM_NP

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, PTHREAD_GETFIRSTLDOM_NP is called to determine the first ldom. PTHREAD_GETNEXTLDOM_NP is then called in a loop (until the call returns EINVAL) to determine the IDs of the remaining ldoms.

The pthread_spu_to_ldom_np() 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 pthread_pset_bind_np() 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 PTHREAD_SCOPE_SYSTEM 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 PTHREAD_SELFTID_NP can be used to refer to the calling thread. The pset PTHREAD_PSETNOCHANGE_NP 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 pthread_processor_bind_np() 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:

PTHREAD_BIND_ADVISORY_NP

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

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

The spu PTHREAD_SPUNOCHANGE_NP may be passed to read the current assignment. The spu PTHREAD_SPUFLOAT_NP 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 scheduling policy shall overrule the processor assignment. For example, when a processor is ready to choose another thread to execute, if the highest priority SCHED_FIFO 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.

PTHREAD_BIND_FORCED_NP

This request is identical to PTHREAD_BIND_ADVISORY_NP 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 SCHED_FIFO 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, cooperating threads should not rely on locality domain assignment in lieu of a synchronization mechanism (such as mutexes).

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 pthread_ldom_bind_np() 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 PTHREAD_SELFTID_NP can be used to refer to the calling thread.

The ldom parameter specifies the new locality domain binding for tid. The value PTHREAD_LDOMNOCHANGE_NP may be passed to only read the current assignment. The value PTHREAD_LDOMFLOAT_NP 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 SCHED_FIFO 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 honoring the scheduling policies.

RETURN VALUE

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

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

Upon successful completion, pthread_processor_id_np(), pthread_ldom_id_np(), pthread_spu_to_ldom_np(), pthread_num_ldomprocs_np(), pthread_processor_bind_np(), pthread_pset_bind_np(), and pthread_ldom_bind_np() return zero. Otherwise, an error number is returned to indicate the error (the errno variable is not set).

Note: In some cases, pthread_processor_bind_np() and pthread_ldom_bind_np() may return a negative value, other than -1, in the answer 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 pthread_processor_id_np(), pthread_ldom_id_np(), pthread_spu_to_ldom_np(), pthread_num_ldomprocs_np(), pthread_processor_bind_np(), pthread_pset_bind_np(), and pthread_ldom_bind_np() functions return the corresponding error number:

EINVAL: The request parameter contains an illegal value.
EINVAL: The spu or ldom parameter contains an invalid ID.
EINVAL: The request parameter is PTHREAD_GETNEXTSPU_NP and spu identifies the last processor.
EINVAL: The request parameter is PTHREAD_GETNEXTLDOM_NP and ldom identifies the last locality domain.
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.
EPERM: request is PTHREAD_BIND_ADVISORY_NP or PTHREAD_BIND_ADVISORY_NP, spu is not PTHREAD_SPUNOCHANGE_NP, and the caller does not have the appropriate permission to change a threads binding to a specific processor.
EPERM: The function is pthread_pset_bind_np() and thread tid does not have necessary permission to bind to the pset.

AUTHOR

pthread_num_processors_np(), pthread_num_ldoms_np(), pthread_num_ldomprocs_np(), pthread_spu_to_ldom_np(), pthread_processor_id_np(), pthread_ldom_id_np(), pthread_processor_bind_np(), pthread_ldom_bind_np(), and pthread_pset_bind_np() were developed by HP.

STANDARDS CONFORMANCE

pthread_num_processors_np(): None.
pthread_num_ldoms_np(): None.
pthread_num_ldomprocs_np(): None.
pthread_spu_to_ldom_np(): None.
pthread_processor_id_np(): None.
pthread_ldom_id_np(): None.
pthread_processor_bind_np(): None.
pthread_ldom_bind_np(): None.
pthread_pset_bind_np(): None.

pthread_processor_bind_np(3T)

Technical documentation

» Table of Contents

» Index