pthread_processor_bind_np(3T)pthread_processor_bind_np(3T)NAMEpthread_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
SYNOPSISPARAMETERS
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 ALSOsleep(3C), rtsched(2), mpctl(2), pset_create(2), pset_bind(2),
sysconf(2).
STANDARDS CONFORMANCE
Pthread Library pthread_processor_bind_np(3T)