From: Adhemerval Zanella <adhemerval.zanella@linaro.org>
To: Rical Jasan <rj@2c3t.io>, Carlos O'Donell <carlos@redhat.com>
Cc: libc-alpha@sourceware.org, Florian Weimer <fweimer@redhat.com>
Subject: Re: [PATCH v8 0/8] Add support for ISO C threads.h
Date: Sat, 21 Jul 2018 13:40:00 -0000 [thread overview]
Message-ID: <57e257ac-07f1-90ad-ee3b-6bc3b08fa1c3@linaro.org> (raw)
In-Reply-To: <5550e6dd-9241-a898-3993-8562d0d9a327@2c3t.io>
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
next prev parent reply other threads:[~2018-07-21 13:40 UTC|newest]
Thread overview: 80+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-02-02 17:04 Adhemerval Zanella
2018-02-02 17:05 ` [PATCH v8 4/8] nptl: Add C11 threads cnd_* functions Adhemerval Zanella
2018-02-02 17:05 ` [PATCH v8 7/8] nptl: Add test cases for ISO C11 threads Adhemerval Zanella
2018-07-13 9:31 ` Florian Weimer
2018-07-13 13:10 ` Adhemerval Zanella
2018-07-13 13:11 ` Florian Weimer
2018-07-13 13:29 ` Adhemerval Zanella
2018-07-17 13:53 ` Adhemerval Zanella
2018-02-02 17:05 ` [PATCH v8 1/8] nptl: Add C11 threads thrd_* functions Adhemerval Zanella
2018-02-08 17:58 ` Gabriel F. T. Gomes
2018-02-09 12:11 ` Adhemerval Zanella
2018-02-26 13:43 ` Gabriel F. T. Gomes
2018-07-06 12:46 ` Florian Weimer
2018-07-10 19:26 ` Adhemerval Zanella
2018-07-11 15:49 ` Szabolcs Nagy
2018-07-11 16:24 ` Adhemerval Zanella
2018-07-12 12:19 ` Florian Weimer
2018-07-12 17:38 ` Adhemerval Zanella
2018-07-13 7:03 ` Florian Weimer
2018-07-12 16:46 ` Florian Weimer
2018-07-12 17:52 ` Adhemerval Zanella
2018-07-12 18:25 ` Florian Weimer
2018-07-12 19:19 ` Adhemerval Zanella
2018-07-12 19:26 ` Florian Weimer
2018-07-12 19:41 ` Adhemerval Zanella
2018-07-12 19:32 ` Adhemerval Zanella
2018-07-12 19:35 ` Florian Weimer
2018-07-12 19:43 ` Adhemerval Zanella
2018-07-13 9:45 ` Florian Weimer
2018-07-13 12:59 ` Adhemerval Zanella
2018-07-13 13:04 ` Florian Weimer
2018-07-13 13:18 ` Adhemerval Zanella
2018-07-13 13:22 ` Florian Weimer
2018-07-13 9:48 ` Florian Weimer
2018-07-25 7:20 ` Andreas Schwab
2018-07-25 7:38 ` Florian Weimer
2018-07-25 10:29 ` Joseph Myers
2018-02-02 17:05 ` [PATCH v8 3/8] nptl: Add C11 threads call_once functions Adhemerval Zanella
2018-07-13 9:32 ` Florian Weimer
2018-02-02 17:05 ` [PATCH v8 8/8] Add manual documentation for threads.h Adhemerval Zanella
2018-02-02 17:05 ` [PATCH v8 6/8] nptl: Add abilist symbols for C11 threads Adhemerval Zanella
2018-07-13 9:50 ` Florian Weimer
2018-07-13 15:49 ` Adhemerval Zanella
2018-07-13 17:49 ` Florian Weimer
2018-07-13 18:47 ` Adhemerval Zanella
2018-07-13 20:00 ` Florian Weimer
2018-07-13 21:09 ` Adhemerval Zanella
2018-07-14 13:50 ` Florian Weimer
2018-07-18 17:40 ` Joseph Myers
2018-07-18 20:02 ` Adhemerval Zanella
2018-07-18 21:50 ` Florian Weimer
2018-02-02 17:05 ` [PATCH v8 5/8] nptl: Add C11 threads tss_* functions Adhemerval Zanella
2018-07-12 16:48 ` Florian Weimer
2018-07-12 20:32 ` Adhemerval Zanella
2018-07-12 20:38 ` Florian Weimer
2018-02-02 17:05 ` [PATCH v8 2/8] nptl: Add C11 threads mtx_* functions Adhemerval Zanella
2018-07-06 12:51 ` Florian Weimer
2018-07-10 12:35 ` Adhemerval Zanella
2018-07-12 18:39 ` Florian Weimer
2018-07-12 20:30 ` Adhemerval Zanella
2018-07-12 20:39 ` Florian Weimer
2018-07-13 13:08 ` Adhemerval Zanella
2018-07-13 13:10 ` Florian Weimer
2018-07-24 12:04 ` Adhemerval Zanella
2018-07-24 16:05 ` Carlos O'Donell
2018-06-27 13:40 ` [PATCH v8 0/8] Add support for ISO C threads.h Adhemerval Zanella
2018-07-19 17:47 ` Adhemerval Zanella
2018-07-19 18:44 ` Carlos O'Donell
2018-07-19 19:12 ` Rical Jasan
2018-07-19 19:58 ` Adhemerval Zanella
2018-07-21 0:26 ` Rical Jasan
2018-07-21 2:12 ` Carlos O'Donell
2018-07-21 6:22 ` Rical Jasan
2018-07-21 13:40 ` Adhemerval Zanella [this message]
2018-07-19 21:26 ` Joseph Myers
2018-07-20 12:32 ` Adhemerval Zanella
2018-07-20 13:22 ` Rical Jasan
2018-07-20 13:54 ` Rical Jasan
2018-07-20 14:04 ` Carlos O'Donell
2018-07-20 15:02 ` [PATCH v8 0/8] Add support for ISO C threads.h [thrd_exit] Rical Jasan
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=57e257ac-07f1-90ad-ee3b-6bc3b08fa1c3@linaro.org \
--to=adhemerval.zanella@linaro.org \
--cc=carlos@redhat.com \
--cc=fweimer@redhat.com \
--cc=libc-alpha@sourceware.org \
--cc=rj@2c3t.io \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).