mutexattr_[gs]etspin

NAME

pthread_mutexattr_getspin_np(), pthread_mutexattr_setspin_np(), pthread_mutex_getyieldfreq_np(), pthread_mutex_setyieldfreq_np() — get and set the mutex spin and yield frequency attributes

SYNOPSIS

#include <pthread.h>

int pthread_mutexattr_setspin_np(pthread_mutexattr_t *attr, int spin);

int pthread_mutexattr_getspin_np(const pthread_mutexattr_t *attr, int *spin);

int pthread_mutex_setyieldfreq_np(int yield);

int pthread_mutex_getyieldfreq_np(int *yield);

PARAMETERS

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 function).
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 optimized application performance on multiprocessor systems.

For pthread_mutexattr_setspin_np() and pthread_mutexattr_getspin_np() the attributes object attr must have previously been initialized with the function pthread_mutexattr_init() before these functions are called.

ATTRIBUTE: spin

Mutexes can be initialized with a spin value which is used by pthread_mutex_lock() for busy-wait iterations on the mutex lock. It is effective only on multiprocessor 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 pthread_mutex_unlock().

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:

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 completing 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. However, 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.

WARNINGS

The setting 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 understanding of mutex contention within the application. Then, experiment with different attribute values, evaluating how mutex contention is affected, response time, and CPU consumption.

RETURN VALUE

Upon successful completion, pthread_mutexattr_setspin_np(), pthread_mutexattr_getspin_np(), pthread_mutex_setyieldfreq_np(), and pthread_mutex_getyieldfreq_np() return zero. Otherwise, an error number is returned to indicate the error (the errno variable is not set).

ERRORS

For each of the following conditions, if the condition is detected, the pthread_mutexattr_setspin_np(), pthread_mutexattr_getspin_np(), pthread_mutex_setyieldfreq_np(), and pthread_mutex_getyieldfreq_np() functions return the corresponding error number:

[EINVAL]: The value specified by attr, spin, or yield is invalid.

AUTHOR

pthread_mutexattr_getspin_np(), pthread_mutexattr_setspin_np(), pthread_mutex_getyieldfreq_np(), and pthread_mutex_setyieldfreq_np() were developed by HP.

STANDARDS CONFORMANCE

pthread_mutexattr_setspin_np(): None.
pthread_mutexattr_getspin_np(): None.
pthread_mutex_setyieldfreq_np(): None.
pthread_mutex_getyieldfreq_np(): None.

mutexattr_[gs]etspin_np(3T)

Technical documentation

» Table of Contents

» Index