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

[Rical Jasan]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: cthreads-docs-v8.2.patch
Type: text/x-patch
Size: 23219 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/libc-alpha/attachments/20180721/d18f6b34/attachment.bin>