Draft pthread_spin_init(2) manual page

[Michael Kerrisk (man-pages)]

Hello Zack,

Hello On 10/18/2017 07:44 PM, Zack Weinberg wrote:
> On Wed, Oct 18, 2017 at 4:10 AM, Michael Kerrisk (man-pages)
> <mtk.manpages@gmail.com> wrote:
>> Hello all,
>>
>> I recently drafted a manual page for the pthread_spin_init() and
>> pthread_spin_destroy() APIs. Comments and suggestions for improvements
>> would be most welcome.
> 
> This should probably cross-reference the pthread_mutex_* manpages and
> say when it is appropriate to use which.  I see you already have some
> of that...
> 
>> NOTES
>>        Spin locks should be employed in conjunction with real-time sched‐
>>        uling policies (SCHED_FIFO, or possibly SCHED_RR).   Use  of  spin
>>        locks   with   nondeterministic   scheduling   policies   such  as
>>        SCHED_OTHER probably indicates a design mistake.  The  problem  is
>>        that  if  a  thread operating under such a policy is scheduled off
>>        the CPU while it holds a spin lock, then other threads will  waste
>>        time  spinning  on  the  lock  until  the lock holder is once more
>>        rescheduled and releases the lock.
>>
>>        Warning: if threads create a deadlock  situation  while  employing
>>        spin locks, those threads will spin forever consuming CPU time.
> 
> but you might want to begin with something like "Most programs should
> use mutexes (pthread_mutex_init(3)) instead of spin locks.  Spin locks
> are primarily useful in conjunction with real-time scheduling ..."
> 
> Also, this is important enough that I'd put it in the DESCRIPTION.

Thanks. I think that's a great phrasing. I added the following at the start 
of DESCRIPTION:

       General  note:  Most  programs  should use mutexes instead of spin
       locks.  Spin locks are primarily useful in conjunction with  real-
       time scheduling policies.  See NOTES.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/