Re: Review: Boost.Threads

From: Eric Friedman (ebf_at_[hidden])
Date: 2001-09-24 19:36:41

--- In boost_at_y..., "Scott McCaskill" <scott_at_m...> wrote:
> > As for changing the name... one name change request that's been 
made
> > several times that I've ignored I'd like to address one last time.
> > The notify_one() and notify_all() methods on condition are more
> > traditionally known as signal() and broadcast() respectively.  I 
was
> > persuaded to change them at one point, but I'm feeling like this 
was
> > a mistake.  I'm leaning towards changing them but I'll need to do 
so
> > in the next day or two, so one final chance to argue this one.
> >
> 
> notify_one and notify_all are more descriptive of what these 
methods do and
> their relationship to each other.  Those who are already familiar 
with
> signal and broadcast will almost certainly already understand the
> functionality behind those names and should have little trouble 
equating new
> names with concepts they already understand.
> 
> For those with less knowledge of the underlying concepts, 
descriptive names
> will be beneficial, while historical names may not be.  broadcast 
is not
> bad, since it implies a potential one-to-many style of 
communication.
> However, I can't see how one could interpret signal to be a 
counterpart to
> broadcast (historical uses aside)--the definition of signal does 
not imply a
> one-to-one relationship between the signaller and the signalled.

I agree entirely with Scott on this issue.  Being one of "those with 
less knowledge of the underlying concepts," I can personally testify 
that I would not have immediately understood the difference between 
notify_one and notify_all if signal and broadcast had been used 
instead.

Another naming issue that has been raised before, and which I do not 
feel has ever been addressed thoroughly, deals with semaphore::up() 
and semaphore::down().  I feel strongly that these should instead be 
named semaphore::increment() and semaphore::decrement(), 
respectively.  This change would serve only to clarify the meaning of 
these functions for the following reasons:

  1) "Increment" and "decrement" are verbs.  While "up" and "down" 
also have verb uses, their use as adjectives, adverbs, etc. is much 
more common.  A verb naming implies an action being done; an 
adjectival naming implies a property being returned.  Since the 
latter is obviously not the case here, "increment" and "decrement" 
are the less ambiguous and thus, IMO, the better choices.

  2) Since a "semaphore" (in English) is "a system of visual 
signaling by two flags held one in each hand" (from www.m-w.com), the 
names "up" and "down" make the subtle implication to an inexperienced 
user that a semaphore can be only "up" or "down" (as a flag can only 
be up or down) -- which is obviously not the case with a 
boost::semaphore.  Rather, since these are counting 
semaphores, "increment" and "decrement" instantly convey the multi-
valued possibilities of the semaphore rather than that of boolean 
up/down values.

Is there something about semaphores that I am just not understanding 
here?  I don't think so, but I'd be happy to learn otherwise.

Thanks,
Eric Friedman