Re: [PATCH v8 0/8] Add support for ISO C threads.h

[Adhemerval Zanella <adhemerval dot zanella at linaro dot org>]

On 21/07/2018 03:22, Rical Jasan wrote:
> On 07/20/2018 07:11 PM, Carlos O'Donell wrote:
>> On 07/20/2018 08:26 PM, Rical Jasan wrote:
> ...
>>> +This section describes the @glibcadj{} ISO C threads implementation.
>>> +To have a deeper understanding of this API, it is strongly recomended
>>
>> s/recomended/recommended/g
> 
> Fixed.
> 
>>> +@deftp {Data Type} thrd_t
>>> +@standards{C11, threads.h}
>>> +A unique object that identifies a thread unequivocally.
>>
>> Suggest:
>> A unique object that identifies one thread.
>>
>> Do more with less.
> 
> I call, and raise you to "a thread".
> 
>>> +@item mtx_recursive
>>> +@standards{C11, threads.h}
>>> +A mutex that supports recursive locking, which means that the owner
>>> +thread can lock it more than once without causing deadlock.
>>
>> Traditional technical language is "owning thread"
>>
>> s/owner thread/owning thread/g
> 
> Fixed.
> 
>>> +@deftypefun int mtx_init (mtx_t *@var{mutex}, int @var{type})
>>> +@standards{C11, threads.h}
>>> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
>>> +@code{mtx_init} creates a new mutex object with type @var{type}.  The
>>> +object pointed to by @var{mutex} is set to the identifier of the newly
>>> +created mutex.
>>> +
>>> +The @code{type} argument may be either @code{mtx_plain} or
>>> +@code{mtx_timed}, optionally combined with @code{mtx_recursive}.
>>
>> This should be expanded to ensure clarity.
>>
>> Suggest:
>> ~~~
>> The @code{type} argument may be either @code{mtx_plain},
>> @code{mtx_timed}, @code{mtx_plain | mtx_recursive}, or 
>> @code{mtx_timed | mtx_recursive}.
>> ~~~
> 
> I turned this into a table.
> 
>>> +@deftypefun int mtx_unlock (mtx_t *@var{mutex})
>>> +@standards{C11, threads.h}
>>> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
>>> +@code{mtx_unlock} unlocks the mutex pointed to by @var{mutex}.  The
>>> +behavior is undefined if the mutex is not locked by the calling
>>> +thread.
>>
>> OK. What about unlocking a lock you already unlocked?
> 
> I don't know.  The specification is quiet on that point, as well as the
> text I was working with.  nptl/mtx_unlock.c in Adhemerval's branch calls
> __pthread_mutex_unlock.  In nptl/pthread_mutex_unlock.c, going through
> the various tests for the mutex type (most of which result in a call to
> lll_unlock or some variant), there are three tests that are conditional
> upon "! lll_islocked", and they all return EPERM.  I believe, however,
> that is an implementation detail we wouldn't necessarily include in the
> manual, so the best I could say here is that it's UB because the spec
> doesn't say anything about it.  (I didn't in the new patch, but I can
> add that in if you like.)
> 
>>> +@deftypefun int cnd_wait (cnd_t *@var{cond}, mtx_t *@var{mutex})
>>> +@standards{C11, threads.h}
>>> +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
>>> +@code{cnd_wait} atomically unlocks the mutex pointed to by @var{mutex}
>>> +and blocks on the condition variable pointed to by @var{cond} until
>>> +the thread is signalled by @code{cnd_signal} or @code{cnd_broadcast}.
>>
>> s/signalled/signaled/g
> 
> Fixed.
> 
>>> +@deftypefun int cnd_timedwait (cnd_t *restrict @var{cond}, mtx_t *restrict @var{mutex}, const struct timespec *restrict @var{time_point})
>>> +@standards{C11, threads.h}
>>> +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
>>> +@code{cnd_timedwait} atomically unlocks the mutex pointed to by
>>> +@var{mutex} and blocks on the condition variable pointed to by
>>> +@var{cond} until the thread is signalled by @code{cnd_signal} or
>>
>> s/signalled/signaled/g
> 
> Fixed.
> 
>>> +@Theglibc{} implements functions to provide @dfn{thread-local
>>> +storage}, which means each thread can have their own variables that
>>> +are not visible by other threads.
>>
>> I would tighten this up a bit like this, since it's less about
>> visibility and more about storage:
>> ~~~
>> @Theglibc{} implements functions to provide @dfn{thread-local
>> storage}. Variables can be defined to have unique storage per-thread,
>> lifetimes that match the thread lifetime, and destructors that cleanup
>> the unique per-thread storage.
>> ~~~
> 
> Fixed.  I joined it into one sentence to bind the explanation a little
> more tightly to the @dfn.
> 
>>> +@emph{Note:} For C++, C++11 or later is required to get the
>>
>> s/get/use/g
>>
>> You "use" a keyword.
> 
> Fixed.
> 
>>> +@defvr Macro TSS_DTOR_ITERATIONS
>>> +@standards{C11, threads.h}
>>> +@code{TSS_DTOR_ITERATIONS} is an integer constant expression
>>> +representing the maximum number of times that destructors will be
>>> +called when a thread terminates.
>>
>> Suggest a broader explanation:
>>
>> @code{TSS_DTOR_ITERATIONS} is an integer constant expression
>> representing the maximum number of iterations over all thread-local
>> destructors at the time of thread termination. This value provides
>> a bounded limit to the destruction of thread-local storage e.g.
>> consider a destructor that creates more thread-local storage.
> 
> Thanks.  I had largely left that one alone.
> 
> Updated patch attached.
> 
> Rical
> 

Thanks, I pushed it on my personal branch [1] with you as author.

[1] https://sourceware.org/git/?p=glibc.git;a=shortlog;h=refs/heads/azanella/c11-threads