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)