This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [RFC] MI non-stop and multiprocess docs.


> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Wed, 12 Nov 2008 20:20:33 +0300
> Cc: gdb-patches@sources.redhat.com
> 
> > Finally, this chapter seems to be not on design of MI, but more about
> > advice to frontend implementors.  So I think it should be renamed
> > accordingly, and some introductory text added to its beginning saying
> > this is the intent of the chapter.
> 
> I don't quite agree. These section describes the main building blocks and 
> concepts of GDB/MI, and is necessary to understand anything in GDB/MI
> docs.

Right, but IMO that isn't "MI design", either.

> > It is best not to leave spaces around "---", the results look better
> > in print.
> 
> Do you think you can summarize such style requirements for GDB manual somewhere?

The canonical place for such style conventions is the Texinfo manual.
It has this advice (in the "Conventions" node):

   * Use three hyphens in a row, `---', to produce a long dash--like
     this (called an "em dash"), used for punctuation in sentences.

Although it doesn't explicitly say to avoid spaces, it does avoid them
itself.  I will ask the Texinfo maintainer to be more explicit about
this.

> > >                                  Status notifications are used to
> > 
> > Wouldn't it be better to make "Status notifications" a separate @item
> > in this list?
> 
> I think they are very similar from frontend point of view -- in that frontend
> does only minimal processing of those notification, and won't break if they
> are not emitted.

That's okay, but it looks to me that after listing 3 items, it is best
to have 3 @items, not 2.

> > "preferable".  Also, perhaps rephrase as "Therefore, we recommend that
> > each MI command ...".  This removes passive tense from the sentence,
> > which makes the sentence more concise and clear.
> 
> I think it's not strong enough. How about:
> 
> 	Therefore, each MI command should explicitly specify which thread and

Fine with me.

> > Whenever you first introduce a term, give it the @dfn markup, which
> > will make stand out in the text.  In this case, since this term is
> > explained elsewhere in the manual, it is also a good idea to add a
> > @pxref to that other node.
> 
> Actually, we don't have a section for CLI async mode, we have a section
> for CLI non-stop mode.

Sorry, I don't follow.  I meant the node "Background Execution".

> > > +that even commands that operate on global state (like global
> > > +variables, or breakpoints), still access the target in the context of
> > > +a specific thread
> > 
> > What do you mean by "global variables" here?  As written, the text
> > seems to say that global variables and breakpoints are commands, or
> > maybe global state, which doesn't sound right to me.  "Breakpoints"
> > could be replaced with "breakpoint commands", but I don't know what
> > replacement to suggest for "global variables".
> 
> global variables, and breakpoints, are examples of the "global state"
> that GDB commands can operate on.

What GDB commands operate on global variables?

> > >                    so frontend should try perform such operations on a
> > > +stopped thread.
> > 
> > I don't see how this conclusion follows from the fact that commands
> > access the target in the context of some thread.  Why doing that "on a
> > stopped thread" will solve whatever problem you are trying to explain
> > here? and what does "operations ON a stopped thread" mean in this
> > context, anyway?
> 
> ... and with the explanation above, if doing operations in context of running
> thread may fail even if that operation only accesses global state, the frontend
> better pick a thread that is stopped.

Do you mean that a frontend should do the equivalent of "thread N"
where N is an ID of a thread that is stopped, before issuing commands?
If so, let's say that explicitly.  "Pick a thread that is stopped" is
not clear enough, at least it confuses me.

> > > +Since the set of allowed commands depends on the target, this
> > > +documention does not list which commands are allowed. Also,
> > > +@value{GDBN} does not try to simulate asynchronous execution of
> > > +commands that fail -- in particular, it does not try to briefly
> > > +interrupt an executing thread to execute a command, and it does not
> > > +try to automatically pick a stopped thread and execute a command in
> > > +the context of that thread.
> > > +
> > > +Two commands that are explicitly required to always work are
> > > +@code{-exec-interrupt}, to stop a thread, and @code{-thread-info}, to
> > > +find the state of each thread.
> > 
> > I fail to understand why these two paragraphs are useful, nor why they
> > are in this particular place.  If the first sentence of the first
> > paragraph is related to the second paragraph, let's put them together,
> > and let's also make the first sentence less general ("this
> > documentation", as written, seems to refer to the entire manual).
> > 
> > As for the second sentence of the first paragraph, I completely fail
> > to grasp the significance of what you are saying, or to parse the
> > "does not try to simulate asynchronous execution of commands that
> > fail" part.  Can you help me understand what you are trying to say
> > here?
> 
> Earlier we've said that GDB commands *may* fail is executed in context of a
> running thread. The immediate question is whether GDB/MI documentation has
> more accurate information what commands will fail in what cases. This
> paragraph states that such information is highly dependent on the target,
> and GDB/MI cannot promise anything. It further tries to state that if target
> cannot perform some operation in the context of a running thread, GDB will
> not try to simulate that, for example, by stopping thread, doing the operation,
> and resuming thread.

Thanks, now I understand.  It seems to me that we don't need to go any
further than say simply

   Which commands will work in the context of a running thread is
   highly target dependent.  However, the two commands
   @code{-exec-interrupt}, to stop a thread, and @code{-thread-info},
   to find the state of a thread, will always work.

> It might be best to reword the last two sentences thusly:
> 
> 	If an expression specified when creating a fixed variable object
> 	refers to a local variable, the variable object becomes bound to the
> 	thread and frame in which the variable object is created.

This is fine, thanks.

> > > +@smallexample
> > > +(gdb)
> > 
> > This should be @value{GDBP}, I think.
> 
> OOC, what practical differences or benefits that will have?

I understand that both GDBN and GDBP exist so that a manual could be
easily produced for a customized version of GDB that calls itself
"gdbfoo" and prompts with "(gdb-foo)", say.  Anyway, this goes way
back before I assumed the responsibility on the GDB docs; perhaps Stan
or other old-timers could add some insights.

> Thanks for feedback. I attach both the revised version of the patch, and the delta
> relatively to the previous version.

The new version is fine, except that there are still instances of only
one space after a period that ends a sentence.

Thanks.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]