Re: Draft pthread_spin_lock(3) manual page

["Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>]

Hi Carlos,

Thanks for looking the page over.

On 18 October 2017 at 17:07, Carlos O'Donell <carlos@redhat.com> wrote:
> On 10/18/2017 01:11 AM, Michael Kerrisk (man-pages) wrote:
>> Hello all,
>>
>> Following on from the pthread_spin_init(3) page, I also recently
>> drafted a manual page for the pthread_spin_lock() and
>> pthread_spin_unlock() APIs. Again, comments and suggestions for
>> improvements would be most welcome.
>
> Overall looks good, just a few nits.
>
>> Thanks,
>>
>> Michael
>>
>> PTHREAD_SPIN_LOCK(3)    Linux Programmer's Manual    PTHREAD_SPIN_LOCK(3)
>>
>> NAME
>>        pthread_spin_lock,   pthread_spin_trylock,  pthread_spin_unlock  -
>>        lock and unlock a spin lock
>>
>> SYNOPSIS
>>        #include <pthread.h>
>>
>>        int pthread_spin_lock(pthread_spinlock_t *lock);
>>        int pthread_spin_trylock(pthread_spinlock_t *lock);
>>        int pthread_spin_unlock(pthread_spinlock_t *lock);
>>
>>        Compile and link with -pthread.
>>
>>    Feature   Test   Macro    Requirements    for    glibc    (see    fea‐
>>    ture_test_macros(7)):
>>
>>        pthread_spin_lock(), pthread_spin_trylock():
>>            _POSIX_C_SOURCE >= 200112L
>>
>> DESCRIPTION
>>        The  pthread_spin_lock()  function locks the spin lock referred to
>>        by lock.  If the spin lock  is  currently  unlocked,  the  calling
>>        thread  acquires  the  lock immediately.  If the spin lock is cur‐
>>        rently locked by another thread, the calling thread spins, testing
>>        the  lock  until  it becomes available, at which point the calling
>>        thread acquires the lock.
>>
>>        Calling pthread_spin_lock() on a lock that is already held by  the
>>        caller results in undefined behavior.
>
> Similarly if you call pthread_spin_lock on an uninitilized lock you get
> undefined behaviour (see EINVAL below). We don't detect this in glibc right

I added the uninitialized lock case to the text.

> now because it's a waste of time, but we might some day for some reason I
> can't know today (say we robustify spin locks). Even if you talk about
> this case in pthread_spin_init(), it bears repeating again here.
>
>>        The  pthread_spin_trylock()  function is like pthread_spin_lock(),
>>        except that if the spin lock referred  to  by  lock  is  currently
>>        locked,  then,  instead  of spinning, the call returns immediately
>>        with the error EBUSY.
>>
>>        The pthread_spin_unlock() function unlocks the spin lock  referred
>>        to  lock.   If  any threads are spinning on the lock, one of those
>>        threads will then acquire the lock.
>>
>>        Calling pthread_spin_unlock() on a lock that is not  held  by  the
>>        caller results in undefined behavior.
>>
>> RETURN VALUE
>>        On  success, there functions return zero.  On failure, they return
>>        an error number.
>>
>> ERRORS
>>        pthread_spin_lock() may fail with the following errors:
>>
>>        EDEADLOCK
>>               The system detected a deadlock condition.
>
> In practice we might have EINVAL some day here to indicate the lock
> was not initialized, and that can be returned for all functions if
> the cost of detection is low.

Okay. (I presume you did not mean any text needs to be added to the page.)

>>        pthread_spin_trylock() can fail with the following errors:
>>
>>        EBUSY  The spin lock is currently locked by another thread.
>
> I always find the 'can fail' wording a bit wishy-washy for my tastes
> and prefer: 'shall fail', along with a statement that defines the
> conditions for failure. I say this only because English is not as
> precise as I'd like so using 'shall' instead of 'can' makes this
> failure mode clearer, indicating to the reader that it will happen
> (here it's a bit obvious from the semantics of the function, since
> otherwise trylock would be useless).

Changed to "shall fail" (but this is not the only page with that problem :-} ).

Thanks,

Michael


>> VERSIONS
>>        These functions first appeared in glibc in version 2.2.
>>
>> CONFORMING TO
>>        POSIX.1-2001.
>>
>> NOTES
>>        Applying any of the functions described on this page to an  unini‐
>>        tialized spin lock results in undefined behavior.
>>
>>        Carefully read NOTES in pthread_spin_init(3).
>>
>> SEE ALSO
>>        pthread_spin_destroy(3), pthread_spin_init(3), pthreads(7)
>>
>> Linux                           2017-09-30           PTHREAD_SPIN_LOCK(3)
>>
>>
>
>
> --
> Cheers,
> Carlos.



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