pthread_mutexattr_getspin_np(3T)pthread_mutexattr_getspin_np(3T)NAMEpthread_mutexattr_getspin_np(), pthread_mutexattr_setspin_np(),
pthread_mutex_getyieldfreq_np(), pthread_mutex_setyieldfreq_np(),
pthread_mutexattr_disable_handoff_np(), pthread_mutex_disable_hand‐
off_np() - get and set mutex spin and yield frequency attributes; dis‐
able mutex-specific or process-wide mutex handoff mode
SYNOPSISPARAMETERS
attr Pointer to the mutex attributes object whose attributes are
to be set/retrieved.
spin This parameter either specifies the new value of the spin
attribute (set function) or points to the memory location
where the spin attribute of attr is to be returned (get func‐
tion).
yield This parameter either specifies the new value of the yield
frequency process-wide attribute (set function) or points to
the memory location where the yield frequency process-wide
attribute is to be returned (get function).
DESCRIPTION
These attributes are used to tune the mutex locking behavior for opti‐
mized application performance on multiprocessor systems.
For and the attributes object attr must have previously been initial‐
ized with the function before these functions are called.
Attribute: spin
Mutexes can be initialized with a spin value which is used by for busy-
wait iterations on the mutex lock. It is effective only on multipro‐
cessor systems. It is ignored on uniprocessor systems.
For bound threads, the procedure to block on a busy mutex is quite
costly. On a multiprocessor system, the thread holding the mutex may
be a few instruction cycles away from releasing it. By performing a
brief busy-wait before actually blocking, the lock path can avoid a
great deal of overhead in these situations.
For many applications, these situations are not rare. Consider a mutex
used to protect a short sequence of code (e.g., to increment a
counter). The mutex is held only for a few instruction cycles (plus
the function call overhead for
The ability to set the spin attribute allows the application writer to
adjust the busy-wait to suit the duration of the common-case critical
section protected by each mutex.
The legal values for the spin attribute are:
The 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 appro‐
priate for mutexes associated with longer critical sections.
Inhibits blocking on the mutex lock altogether.
The function will busy-wait on the mutex lock until it is
acquired.
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 busy-wait, how frequently the
processor should be yielded (via allowing other threads to execute.
When the number of threads exceeds the number of processors in a sys‐
tem, a busy-wait on a mutex can sometimes have an adverse effect. The
busy-wait itself can prevent the thread holding the lock from complet‐
ing the associated critical section of code. By yielding the processor
on occasion, the thread attempting the lock may allow the thread hold‐
ing 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:
The busy-wait loop in
will yield the processor after each specified number of iter‐
ations of the spin loop (where the total number of iterations
is controlled by the per-mutex spin attribute).
Inhibits yielding in the mutex lock altogether.
Uses a built-in default value for the frequency of yields in the
busy-wait loop.
The and functions are provided for binary compatibility purposes only.
They will not have any noticeable effect on mutexes.
RETURN VALUE
and return the following values:
Successful completion.
Failure.
The returned value is an error number defined in the ERRORS sec‐
tion. (The variable is not set).
ERRORS
If an error is detected, and return one of the following error numbers.
The value specified by
attr, spin, or yield is invalid.
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.
The programmer must analyze performance carefully to obtain an under‐
standing of mutex contention within the application. Then, experiment
with different attribute values, evaluating how mutex contention is
affected, response time, and CPU consumption.
AUTHOR
and were developed by HP.
SEE ALSOpthread_create(3T), pthread_mutex_init(3T), pthread_mutexattr_init(3T),
rtsched(2)STANDARDS CONFORMANCE
Pthread Librarpthread_mutexattr_getspin_np(3T)
