Re: [PATCH 3/9 v7] Introduce target_{stop,continue}_ptid

[Doug Evans <dje at google dot com>]

Pedro Alves writes:
 > On 08/29/2014 02:51 PM, Gary Benson wrote:
 > 
 > > +/* See target/target.h.  */
 > > +
 > > +void
 > > +target_stop_ptid (ptid_t ptid)
 > > +{
 > > +  struct target_waitstatus status;
 > > +  int was_non_stop = non_stop;
 > > +
 > > +  non_stop = 1;
 > > +  target_stop (ptid);
 > > +
 > > +  memset (&status, 0, sizeof (status));
 > > +  target_wait (ptid, &status, 0);
 > > +
 > > +  non_stop = was_non_stop;
 > > +}
 > 
 > One thing that was bugging me was that given that the names
 > of target_stop and target_stop_ptid are so similar and that
 > they have the same signature is ripe for confusion.
 > 
 > I just now noticed the elephant in the room -- target_stop is
 > asynchronous, doesn't wait for a stop, while and target_stop_ptid
 > is synchronous.  Would you mind renaming this to target_stop_wait
 > or some such?  And then add an explicit "and wait for it to stop"
 > or some such to the function's description.

target_stop_and_wait would be a significantly more readable to me.
["stop_wait" makes me pause too long to figure out what was meant]

Or if a plain reading of "target_stop" implies waiting,
then rename target_stop to target_stop_no_wait or target_stop_async.
and use "target_stop" for "target stop and wait".

Do we want a convention for marking async vs sync routines?
e.g. append every async routine that is otherwise ambiguous with _async?
Or if gdb is becoming generally async, turn it around and
append _sync to every sync routine that is otherwise ambiguous.
[Or even allow both in certain instances.]
That way we'd no longer have to have individual discussions
whenever the topic comes up.