HP-UX Reference (11i v3 07/02) - 3 Library Functions N-Z (vol 7)

p
pthread_mutexattr_getspin_np(3T) pthread_mutexattr_getspin_np(3T)
(Pthread Library)
positive integer
The pthread_mutex_lock()
function will busy-wait on the mutex lock for the specified
number of iterations before blocking the thread, unless the lock is acquired sooner. Larger spin
values would be appropriate for mutexes associated with longer critical sections.
PTHREAD_MUTEX_SPINONLY_NP
Inhibits blocking on the mutex lock altogether. The
pthread_mutex_lock()
function will
busy-wait on the mutex lock until it is acquired.
PTHREAD_MUTEX_SPINDEFAULT_NP
Uses a built-in default value for the number of busy-wait iterations.
Attribute: yield
Note that the yield attribute is not a per-mutex attribute, but is process-wide. That is, it affects the
behavior of all mutexes.
The yield attribute specifies, for the
pthread_mutex_lock()
busy-wait, how frequently the processor
should be yielded (via
sched_yield()
), allowing other threads to execute.
When the number of threads exceeds the number of processors in a system, a busy-wait on a mutex can
sometimes have an adverse effect. The busy-wait itself can prevent the thread holding the lock from com-
pleting the associated critical section of code. By yielding the processor on occasion, the thread attempting
the lock may allow the thread holding the lock to reach the point at which it can release the lock. How-
ever, it still avoids the costly path to block on the mutex.
The legal values for the yield attribute are:
positive integer
The busy-wait loop in pthread_mutex_lock()
will yield the processor after each specified
number of iterations of the spin loop (where the total number of iterations is controlled by the
per-mutex spin attribute).
PTHREAD_MUTEX_YIELDNEVER_NP
Inhibits yielding in the mutex lock altogether.
PTHREAD_MUTEX_YIELDFREQDEFAULT_NP
Uses a built-in default value for the frequency of yields in the busy-wait loop.
The pthread_mutexattr_disable_handoff_np()
and
pthread_mutex_disable_handoff_np()
functions are provided for binary compatibility purposes
only. They will not have any noticeable effect on mutexes.
RETURN VALUE
pthread_mutexattr_setspin_np()
, pthread_mutexattr_getspin_np()
,
pthread_mutex_setyieldfreq_np()
, pthread_mutex_getyieldfreq_np()
,
pthread_mutexattr_disable_handoff_np()
, and
pthread_mutex_disable_handoff_np()
return the following values:
0 Successful completion.
<>0 Failure. The returned value is an error number defined in the ERRORS section. (The
errno vari-
able is not set).
ERRORS
If an error is detected,
pthread_mutexattr_setspin_np()
,
pthread_mutexattr_getspin_np(), pthread_mutex_setyieldfreq_np()
, and
pthread_mutex_getyieldfreq_np() return one of the following error numbers.
[EINVAL] The value specified by attr, spin,oryield is invalid.
[EINVAL]
pthread_mutex_disable_handoff_np()
was called after the process became
multithreaded.
WARNINGS
The settings of the spin and yield attributes can, as well as improve application performance, easily lead to
degraded performance. The CPU consumption of the application may be increased. Settings which work
well for a small number of threads may do poorly for larger numbers of threads. The optimal settings will
vary depending upon hardware and operating system configuration. Minor changes in the application itself
may require retuning of these attributes.
222 Hewlett-Packard Company − 2 − HP-UX 11i Version 3: February 2007