Discussion:
Awkward wording in description of thrd_equal function
(too old to reply)
Keith Thompson
2015-04-03 02:32:37 UTC
Permalink
Raw Message
N1570 7.26.1p4 says that a `thrd_t` is "a complete object type that
holds an identifier for a thread". (It's clear enough that "identifier"
doesn't have the meaning given in 6.4.2; that's not what I'm discussing
here.)

The description of the thrd_equal function is:

Synopsis

1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);

Description

2 The thrd_equal function will determine whether the thread
identified by thr0 refers to the thread identified by thr1.

Returns

3 The thrd_equal function returns zero if the thread thr0 and the
thread thr1 refer to different threads. Otherwise the thrd_equal
function returns a nonzero value.

The intent is clear enough (it returns non-zero if thr0 and thr1 refer
to the same thread, zero if they don't), but the wording is awkward.
Both the description and the "Returns" section mix "refers to" and
"identified by", and implies that a thread *refers to* another thread.
And this is the only use of "refers" in the section on <threads.h>.

thr0 and thr1 are not threads; they're thrd_t objects which *identify*
threads.

Suggested wording:

Synopsis

1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);

Description

2 The thrd_equal function will determine whether the thread identified
by thr0 and the thread identified by thr1 are the same thread.

Returns

3 The thrd_equal function returns zero if the thr0 and the thr1
identify different threads. Otherwise the thrd_equal function
returns a nonzero value.
--
Keith Thompson (The_Other_Keith) kst-***@mib.org <http://www.ghoti.net/~kst>
Working, but not speaking, for JetHead Development, Inc.
"We must do something. This is something. Therefore, we must do this."
-- Antony Jay and Jonathan Lynn, "Yes Minister"
Kaz Kylheku
2015-04-03 03:38:07 UTC
Permalink
Raw Message
On 2015-04-03, Keith Thompson <kst-***@mib.org> wrote ...
... well, of course "Keith Thompson", the name, didn't write anything;
Post by Keith Thompson
thr0 and thr1 are not threads; they're thrd_t objects which *identify*
threads.
Actually: thr0 and thr1 are declared names in some scope, which
identify objects, which in turn hold values, which identify threads!

But it's okay to collapse all those levels of reference and just
say that thr0 and thr1 are threads.

Just like it's quite conventional to say that f is a stream, given "FILE *f",
rather than an identifier which names a value, which points to an object, which
represents a stream.

The reason that this works is that usually the references involved are stable.
What I mean by stable is this:

- there is no suspicion, in the given context, that thr0 will be redeclared
to refer to a different object, or that there is any confusion or ambiguity
about what the name refers to.

- there is no concern that the value in thr0 will be replaced by another
value.

- there is no concern that the value in thr0 will suddenly change in meaning
so that it refers to a different thread.

So the levels of reference form a simple, stable chain, which readily and
conveniently collapses in discussion, so that thr0 is a thread.
Keith Thompson
2015-04-03 21:00:08 UTC
Permalink
Raw Message
Post by Kaz Kylheku
... well, of course "Keith Thompson", the name, didn't write anything;
Post by Keith Thompson
thr0 and thr1 are not threads; they're thrd_t objects which *identify*
threads.
Actually: thr0 and thr1 are declared names in some scope, which
identify objects, which in turn hold values, which identify threads!
But it's okay to collapse all those levels of reference and just
say that thr0 and thr1 are threads.
Just like it's quite conventional to say that f is a stream, given "FILE *f",
rather than an identifier which names a value, which points to an object, which
represents a stream.
[snip]

Sure, it's ok to be a little "sloppy" in saying that, for example, "foo
is an array" rather than "foo is the identifier defined as the name of
an array object". And in the description of thrd_equal, I doubt that
anyone would misunderstand the intent (though it did take me a little
while to wade through the wording).

I prefer more precise wording particularly in a standard document. And
in this case, the choice of words in the description of thrd_equal is
notably different from the descriptions of the other thrd_* functions.

My concern is about consistency as well as precision.
--
Keith Thompson (The_Other_Keith) kst-***@mib.org <http://www.ghoti.net/~kst>
Working, but not speaking, for JetHead Development, Inc.
"We must do something. This is something. Therefore, we must do this."
-- Antony Jay and Jonathan Lynn, "Yes Minister"
James Kuyper
2015-04-03 09:50:58 UTC
Permalink
Raw Message
Post by Keith Thompson
N1570 7.26.1p4 says that a `thrd_t` is "a complete object type that
holds an identifier for a thread". (It's clear enough that "identifier"
doesn't have the meaning given in 6.4.2; that's not what I'm discussing
here.)
Synopsis
1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);
Description
2 The thrd_equal function will determine whether the thread
identified by thr0 refers to the thread identified by thr1.
Returns
3 The thrd_equal function returns zero if the thread thr0 and the
thread thr1 refer to different threads. Otherwise the thrd_equal
function returns a nonzero value.
The intent is clear enough (it returns non-zero if thr0 and thr1 refer
to the same thread, zero if they don't), but the wording is awkward.
Both the description and the "Returns" section mix "refers to" and
"identified by", and implies that a thread *refers to* another thread.
And this is the only use of "refers" in the section on <threads.h>.
thr0 and thr1 are not threads; they're thrd_t objects which *identify*
threads.
Synopsis
1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);
Description
2 The thrd_equal function will determine whether the thread identified
by thr0 and the thread identified by thr1 are the same thread.
Returns
3 The thrd_equal function returns zero if the thr0 and the thr1
identify different threads. Otherwise the thrd_equal function
returns a nonzero value.
I agree with both your objection and your proposed fix.
--
James Kuyper
Kaz Kylheku
2015-04-03 14:04:27 UTC
Permalink
Raw Message
Post by James Kuyper
I agree with both your objection and your proposed fix.
More precisely, the person *identified* by the pronoun "I" (in a context where
that refers to the same person as that who is also identified by "James
Kuyper") agrees with the amendment that is identified as the "proposed fix".
Tim Rentsch
2015-04-03 19:50:41 UTC
Permalink
Raw Message
Post by Keith Thompson
N1570 7.26.1p4 says that a `thrd_t` is "a complete object type
that holds an identifier for a thread". (It's clear enough that
"identifier" doesn't have the meaning given in 6.4.2; that's not
what I'm discussing here.)
Synopsis
1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);
Description
2 The thrd_equal function will determine whether the thread
identified by thr0 refers to the thread identified by thr1.
Returns
3 The thrd_equal function returns zero if the thread thr0 and
the thread thr1 refer to different threads. Otherwise the
thrd_equal function returns a nonzero value.
The intent is clear enough (it returns non-zero if thr0 and thr1
refer to the same thread, zero if they don't), but the wording is
awkward. Both the description and the "Returns" section mix
"refers to" and "identified by", and implies that a thread *refers
to* another thread. And this is the only use of "refers" in the
section on <threads.h>.
thr0 and thr1 are not threads; they're thrd_t objects which
*identify* threads.
I support your reaction, and in fact would say it more strongly:
IMO the existing text is not just awkward but flat out wrong,
for reasons that you identify.
Post by Keith Thompson
Synopsis
1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);
Description
2 The thrd_equal function will determine whether the thread
identified by thr0 and the thread identified by thr1 are the
same thread.
Returns
3 The thrd_equal function returns zero if the thr0 and the thr1
identify different threads. Otherwise the thrd_equal function
returns a nonzero value.
I think using "refer" is more consistent with the style in other
parts of the Standard. Partly with that in mind here is a
proposed alternative:

1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);

Description

2 The thrd_equal function will determine whether the two thread
identifiers thr0 and thr1 refer to the same thread.

Returns

3 The thrd_equal function returns zero if thread identifier
thr0 and thread identifier thr1 refer to distinct threads.
Otherwise the thrd_equal function returns a nonzero value.

Having said that, either suggested re-write is an improvement
on the original. (Let me add though that the second and third
"the"s in the previous paragraph 3 are somewhat ungrammatical;
a bit of wordsmithing would be needed for that.)
Keith Thompson
2015-04-03 20:57:11 UTC
Permalink
Raw Message
Post by Tim Rentsch
Post by Keith Thompson
N1570 7.26.1p4 says that a `thrd_t` is "a complete object type
that holds an identifier for a thread". (It's clear enough that
"identifier" doesn't have the meaning given in 6.4.2; that's not
what I'm discussing here.)
Synopsis
1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);
Description
2 The thrd_equal function will determine whether the thread
identified by thr0 refers to the thread identified by thr1.
Returns
3 The thrd_equal function returns zero if the thread thr0 and
the thread thr1 refer to different threads. Otherwise the
thrd_equal function returns a nonzero value.
The intent is clear enough (it returns non-zero if thr0 and thr1
refer to the same thread, zero if they don't), but the wording is
awkward. Both the description and the "Returns" section mix
"refers to" and "identified by", and implies that a thread *refers
to* another thread. And this is the only use of "refers" in the
section on <threads.h>.
thr0 and thr1 are not threads; they're thrd_t objects which
*identify* threads.
IMO the existing text is not just awkward but flat out wrong,
for reasons that you identify.
Post by Keith Thompson
Synopsis
1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);
Description
2 The thrd_equal function will determine whether the thread
identified by thr0 and the thread identified by thr1 are the
same thread.
Returns
3 The thrd_equal function returns zero if the thr0 and the thr1
identify different threads. Otherwise the thrd_equal function
returns a nonzero value.
I think using "refer" is more consistent with the style in other
parts of the Standard.
I chose to use "identify" because that's consistent with the rest of
section 7.26, including the definition of type "thrd_t" as "a complete
object type that holds an identifier for a thread"; elsewhere, it's
reasonably consistent about saying that a thrd_t object "identifies" a
thread. (Perhaps "identifies" would be better than "holds an identifier
for" in the description of cnd_t, thrd_t, tss_t, and mtx_t, but that's
not as big a deal.) I like "identifies" more than "refers to", but I
wouldn't object to changing "identifies" to "refers", as long as the
change is made throughout 7.26.
Post by Tim Rentsch
Partly with that in mind here is a
1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);
Description
2 The thrd_equal function will determine whether the two thread
identifiers thr0 and thr1 refer to the same thread.
Returns
3 The thrd_equal function returns zero if thread identifier
thr0 and thread identifier thr1 refer to distinct threads.
Otherwise the thrd_equal function returns a nonzero value.
Having said that, either suggested re-write is an improvement
on the original. (Let me add though that the second and third
"the"s in the previous paragraph 3 are somewhat ungrammatical;
a bit of wordsmithing would be needed for that.)
Sorry, that was just sloppy editing on my part.

Another glitch I just noticed: The description of thrd_equal says it
"will determine ...". The behavior of all the other functions in 7.26
is described in the present tense (except for the "shall" in the
description of thrd_exit, 7.26.5.5).

Here's my revised suggested wording. Changes:
- Remove the excess "the"s;
- Shorten pargraph 2;
- Removethe use of "will";
- Reorganize pararaph 3 to show the true result first.

Synopsis

1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);

Description

2 The thrd_equal function determines whether thr0 and thr1 identify
the same thread.

Returns

3 The thrd_equal function returns a non-zero value if thr0 and thr1 identify
the same thread. Otherwise the thrd_equal function returns zero.
--
Keith Thompson (The_Other_Keith) kst-***@mib.org <http://www.ghoti.net/~kst>
Working, but not speaking, for JetHead Development, Inc.
"We must do something. This is something. Therefore, we must do this."
-- Antony Jay and Jonathan Lynn, "Yes Minister"
Tim Rentsch
2015-04-04 15:11:50 UTC
Permalink
Raw Message
Post by Keith Thompson
Post by Tim Rentsch
Post by Keith Thompson
N1570 7.26.1p4 says that a `thrd_t` is "a complete object type
that holds an identifier for a thread". (It's clear enough that
"identifier" doesn't have the meaning given in 6.4.2; that's not
what I'm discussing here.)
Synopsis
1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);
Description
2 The thrd_equal function will determine whether the thread
identified by thr0 refers to the thread identified by thr1.
Returns
3 The thrd_equal function returns zero if the thread thr0 and
the thread thr1 refer to different threads. Otherwise the
thrd_equal function returns a nonzero value.
The intent is clear enough (it returns non-zero if thr0 and thr1
refer to the same thread, zero if they don't), but the wording is
awkward. Both the description and the "Returns" section mix
"refers to" and "identified by", and implies that a thread *refers
to* another thread. And this is the only use of "refers" in the
section on <threads.h>.
thr0 and thr1 are not threads; they're thrd_t objects which
*identify* threads.
IMO the existing text is not just awkward but flat out wrong,
for reasons that you identify.
Post by Keith Thompson
Synopsis
1 #include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);
Description
2 The thrd_equal function will determine whether the thread
identified by thr0 and the thread identified by thr1 are the
same thread.
Returns
3 The thrd_equal function returns zero if the thr0 and the thr1
identify different threads. Otherwise the thrd_equal function
returns a nonzero value.
I think using "refer" is more consistent with the style in other
parts of the Standard.
I chose to use "identify" because that's consistent with the rest
of section 7.26, including the definition of type "thrd_t" as "a
complete object type that holds an identifier for a thread";
elsewhere, it's reasonably consistent about saying that a thrd_t
object "identifies" a thread. (Perhaps "identifies" would be
better than "holds an identifier for" in the description of cnd_t,
thrd_t, tss_t, and mtx_t, but that's not as big a deal.) I like
"identifies" more than "refers to", but I wouldn't object to
changing "identifies" to "refers", as long as the change is made
throughout 7.26.
I agree that "identified by" is more consistent with the style
in other parts of 7.26. I still think that "refer" is more
consistent with the style in other parts of that Standard
generally, which IMO is at least as strong a consideration.
(I haven't looked at other parts of 7.26 to see whether
changing them also makes sense or is feasible.) Also I find
the "thread identified by" construction rather grating, both
because of the passive voice and because of putting focus
on the thread(s) rather than the two thrd_t arguments. Either
way though is still a definite improvement on the original.

Loading...