Draft pthread_spin_init(2) manual page

[Michael Kerrisk (man-pages)]

Hi Thomas,

On 10/18/2017 09:19 PM, Thomas Gleixner wrote:
> On Wed, 18 Oct 2017, Florian Weimer wrote:
> 
>> On 10/18/2017 10:10 AM, Michael Kerrisk (man-pages) wrote:
>>
>>> DESCRIPTION
>>>         The  pthread_spin_init() function allocates any resources required
>>>         for the use of the spin lock referred to by lock  and  initializes
>>>         the  lock  to be in the unlocked state.  The pshared argument must
>>>         have one of the following values:
>>
>> I think somewhere this should say that it is not possible to change the
>> address of a spinlock after initialization (you can't memcpy it somewhere else
>> and expect that it will keep working).  Other pthread objects have the same
>> problem, of course.
>>
>>> 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.
>>
>> Isn't the more important concern whether there are sufficient resources to run
>> all the threads that block on spinlocks?
> 
> Of course that's also a valid problemm, but I wouldn't say its worse than
> the others.

So, Florian, I did not directly address your comments in the changes so
far. If you have some specific words, you think I should add, beyong those
below, let me know.

> User space spinlocks are prone to priority inversion and unbound spin times
> by definition. A programmer using those has to be exceptionally careful not
> only in the code, but also in terms of system configuration, thread
> placement and priority assignment. User space spinlocks are not applicable
> for general locking problems and yes, the man page should make this very
> clear.

Thanks. I added the following, based pretty much directly on
your wording:

       User space spin locks are prone, by definition, to priority inver‐
       sion and unbound spin times.  A programmer using spin  locks  must
       be  exceptionally  careful not only in the code, but also in terms
       of system configuration, thread placement,  and  priority  assign‐
       ment.   User-space spin locks are not applicable for general lock‐
       ing problems.

Cheers,

Michael

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