Re: Review: Boost.Threads

From: williamkempf_at_[hidden]
Date: 2001-09-26 16:35:56

--- In boost_at_y..., "Scott McCaskill" <scott_at_m...> wrote:
> > > > * Q: notify_* readable by non-experts, signal/broadcast not?
> > > >
> > > > A:
> > > >
> > > > It is a feature that signal/broadcast are unreadable by non-
> > experts. This
> > > > causes an immediate task-switch to documentation reading mode.
> > > >
> > >
> > > That borders on intentional obfuscation.  Classes and methods
> > should be
> > > named according to what they are or what they do, respectively.
> >
> > And both signal() and broadcast() are meaningful for what is done.
> 
> broadcast is ok, signal is not.  As I explained earlier, the 
meaning of the
> word signal does NOT connotate a one-to-one relationship between 
signaller
> and signalled, and for that reason it is a poor counterpart to 
broadcast.

With out tacking on _one to a name, there is no name that conveys a 
one to one realationship in this case.  So signal_one() and broadcast
() instead.  Seems like too much of an attempt to clarify things here 
to me.  Regardless, this ignores the historic inertia.

> > Not as intuitive as the others for newbies, but I find this 
argument
> > less compelling then the inertia of historic usage.
> 
> This is not merely about making things easier for newbies.  The 
names of
> these methods will be of marginal assistance (or hinderance) at 
best in
> aiding a newbie in understanding the concepts behind the names.  
Rather,
> this is about making code more readable via the use of mnemonic 
names.

More readable to whom?  To a non-newbie signal() and broadcast() are 
extremely readable and understandable.  That's part of the point 
about historic inertia.
 
> >Again, I can't
> > state this enough.  Newbies should *NOT* be attempting to learn 
how
> > to write MT programs by looking at MT code.  It's just too
> > dangerous.
> 
> I agree that they shouldn't learn ONLY by looking at code.. but 
looking at a
> well written sample program is definitely an important part of 
learning
> about MT programming.  It's rarely sufficient to learn about these 
concepts
> in the abstract; that's a large part of the value of the sample 
programs.

This is where the second part about the point of historic inertia 
comes in, and you failed to see it in what I said.  So I'll try to 
elaborate.  Nearly all literature on this concept is going to use the 
terms signal() and broadcast().  This is the abstract part.  If the 
library, the physical part, uses notify_one() and notify_all() then 
there's a point of contention between the abstract and the physical 
which creates understandability problems for the newbie.

This is also a problem for the expert.  The expert is going to be 
very familiar with the names signal() and broadcast() because of the 
historical inertia and will find the attempt to switch to different 
names is vexing, at least for a period of adjustment.  I implemented 
Boost.Threads and have used the new names a lot because of this, and 
I still find my mind thinking either signal() or broadcast() and my 
fingers starting to type these names.

> > Threading is a complex and error prone way of
> > programming, no matter how intuitive the idea of it is, or how
> > intuitive the interface names are.  And when these newbies go to 
look
> > at the literature they will find it confusing that everyone else 
uses
> > terminology that we don't use in Boost.Threads.
> >
> > > > notify_one/notify_all are readable enough that a non-expert 
would
> > be
> > > tempted
> > > > to _not_ check what their precise semantics are - and get 
burned.
> > > >
> > >
> > > One could make that argument for any well-named, non-trivial
> > function.  API
> > > names are meant to be mnemonic, not substitues for 
documentation.
> >
> > Exactly, and the vast library of documentation on the concepts (as
> > opposed to the Boost.Threads library and it's documentation) will 
use
> > the names signal() and broadcast().
> >
> 
> Firstly, I don't think it's a given that most newbies will go out 
and read a
> lot of other literature about condition variables.  Sure, some will-
-but I
> think a lot of people will rely largely on the boost documentation 
and the
> sample programs.  The extent to which this is desireable or 
undesireable is
> not relevant.

I disagree totally about the relevance here.  Boost can't hope to 
document this very complex subject to any extent that will be truly 
useful for a newbie.  He might be able to crank out a few things 
based on this cursory level, but he'll quickly find himself in the 
need of deeper understanding and when he turns to standard literature 
on the topic he'll find there's a disconnect because of the differing 
names.
 
> Secondly, equating different names is relatively easy, and the 
differences
> can even provide some additional insight into the underlying 
concepts.  It's
> getting a solid understanding of the underlying concepts that is
> challenging, regardless of the names.  Given this, I see no reason 
to settle
> for names that are less descriptive.

Equating different names is not necessarily easy.  And when the 
concept is complex enough *ANY* additional complexity, no matter how 
slight, can be a major hinderance to comprehension.

Bill Kempf