NAME
pthread_num_processors_np(), pthread_processor_bind_np(), pthread_processor_id_np() — determine how many processors are installed in the system, bind threads to processors, and determine processor IDs; respectively.
SYNOPSIS
#include <pthread.h>
int pthread_num_processors_np(void);
int pthread_processor_bind_np(
int request,
pthread_spu_t *answer,
pthread_spu_t spu,
pthread_t tid
);
int pthread_processor_id_np(
int request,
pthread_spu_t *answer,
pthread_spu_t spu
);
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.
- tid
This parameter gives the value of the thread id for certain requests.
DESCRIPTION
These functions
provide a means of determining how many processors are installed in the
system and assigning threads to run on specific processors.
The
pthread_num_processors_np()
function returns the number of processors currently installed
on the system.
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 system. The
spu
argument is ignored.
- PTHREAD_GETNEXTSPU_NP
This request stores in the
answer
parameter the ID of the next processor in the system 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.
The
pthread_processor_bind_np()
function
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).
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 request assigns thread
tid
to processor
spu.
Since the new spu assignment is returned in the
answer
parameter, the spu
PTHREAD_SPUNOCHANGE_NP
may be passed to read the current assignment. The tid
PTHREAD_SELFTID_NP
can be used to refer to the calling thread. The value
PTHREAD_SPUFLOAT_NP
may be passed in the
spu
parameter 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).
RETURN VALUE
pthread_num_processors_np()
always returns the number of processors on the system.
It never fails.
Upon successful completion,
pthread_processor_id_np()
returns zero. Otherwise, an error number is returned to indicate the error
(the
errno
variable is not set).
Upon successful completion,
pthread_processor_bind_np()
returns zero. Otherwise, an error number is returned to indicate the error
(the
errno
variable is not set).
ERRORS
If any of the following occur, the
pthread_processor_id_np()
and
pthread_processor_bind_np()
functions return the corresponding error number:
- [EINVAL]
The
request
parameter contains an illegal value.
- [EINVAL]
The
request
parameter is
PTHREAD_GETNEXTSPU_NP
and
spu
identifies the last processor.
- [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_FORCED_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.
AUTHOR
pthread_num_processors_np(),
pthread_processor_id_np(),
and
pthread_num_processor_bind_np()
were developed by HP.
STANDARDS CONFORMANCE
pthread_num_processors_np(): None.
pthread_processor_id_np(): None.
pthread_processor_bind_np(): None.
