pthread_mutexattr_getspin_np(3T)										  pthread_mutexattr_getspin_np(3T)

NAME

       pthread_mutexattr_getspin_np(),	   pthread_mutexattr_setspin_np(),    pthread_mutex_getyieldfreq_np(),	  pthread_mutex_setyieldfreq_np(),
       pthread_mutexattr_disable_handoff_np(), pthread_mutex_disable_handoff_np() - get and set mutex spin and yield frequency attributes; disable
       mutex-specific or process-wide mutex handoff mode

SYNOPSIS


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  mem-
		 ory 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 and the attributes object attr must have previously been initialized 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 multi-
       processor 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 criti-
       cal 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 appropriate 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 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  proces-
       sor  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:

       The busy-wait loop in
		 will yield the processor after each specified number of iterations of the spin loop (where the total number of iterations is con-
		 trolled 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 section.  (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  num-
       bers of threads.  The optimal settings will vary depending upon hardware and operating system configuration.  Minor changes in the applica-
       tion 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.

AUTHOR

       and were developed by HP.

SEE ALSO

       pthread_create(3T), pthread_mutex_init(3T), pthread_mutexattr_init(3T), rtsched(2)

STANDARDS CONFORMANCE

								  Pthread Library				  pthread_mutexattr_getspin_np(3T)