Re: [RFA] checkpoint / restart, and multi-fork debugging

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 06 Dec 2005 14:46:09 -0800
> From: Michael Snyder <msnyder@redhat.com>
> 
> OK, ready for submission.

Thanks!

My comments, mostly about the manual, are below.

> + /*
> +  * Fork list methods:
> +  */

This and other similar comments is not according to coding standards.

> + /* Print information about currently known forks.
> +  */

And neither is this.

> + Set number of finish commands gdb should do on restart of a fork."), _("\

Can we add some clarification to this text?  I'm not sure users will
understand what is ``restart of a fork'' and why they'd wish to do
finish commands then.

> + * Checkpoint/Restart::          Setting a 'bookmark' to return to later

Please don't use '..' in Texinfo.  If you wanted to quote the enclosed
string, use ``..''.  If you want it emphasized (e.g., by italics), use
@emph{..} or @dfn{..}.

> + If you want to debug both the parent and child processes, use the
> + command @w{@code{set detach-on-fork}}.

I'd like to have a @cindex entry here, something like this:

  @cindex debugging multiple processes

Also, since this is Linux-specific, I think we should say that this is
available only on some platforms.

> + The child process (or parent process, depending on the value of
> + @var{follow-fork-mode}) will be detached and allowed to run 

follow-fork-mode is not a meta-syntactic variable, it doesn't stand
for something else.  So it should be in @code, not in @var.

> + One process (child or parent, depending on the value of 
> + @var{follow-fork-mode}) is debugged as usual, while the other

Same here.

> + If you choose to set @var{detach-on-follow} mode off, then gdb will
                                                               ^^^
@value{GDBN}

> + To quit debugging one of the forked processes, you can either 
> + detach it
    ^^^^^^^^^
I think "detach from it" is better.

> + Detach the process identified by @value{GDBN} fork number @var{fork-id},
    ^^^^^^^^^^^^^^^^^^
"Detach from the process"

> + @node Checkpoint/Restart
> + @section Setting a 'bookmark' to return to later

See what I wrote above about '..'.

> + 
> + @cindex checkpoint
> + @cindex restart
> + @cindex bookmark

I think "@cindex snapshot of a process" would be a good addition here.

Another useful index entry might be @cindex rewind program state".

> + 
> + On certain operating systems @footnote{Currently, only
> + @sc{gnu}/Linux.},

@footnote should immediately follow the preceding text, without any
intervening whitespace.  That is because it is replaced by the
over-scripted number, and you want that to follow the last letter of
the preceding word.

>   @value{GDBN} is able to save a @code{snapshot} of a
> + program's state, called a @code{checkpoint}, and come back to it
> + later.

It looks like you wanted to emphasize "snapshot" and "checkpoint".
The latter is a new term you are introducing here, so it should be in
@dfn, which will emphasize it properly.  As for the former, either
leave it unmarked, or use @dfn for it as well.

> + Returning to a @code{checkpoint} effectively undoes everything that
> + has happened in the program since the @code{checkpoint} was saved.

Why did you use @code here?  Why should checkpoint stand out?

> + is assigned a small integer @code{id}, similar to a @code{breakpoint id}.

Again, I don't think "breakpoint id" here warrants any markup, so
please explain why you used @code.

> + Returning to a previously saved checkpoint will restore all program
> + state internal to the program being debugged

``restore all program state internal to the program'' sounds awkward.
How about ``restore the internal program state'' instead

> + Finally, there is one bit of internal program state that will be
> + different when you return to a checkpoint -- the program's process

This should be 3 dashes in a row, "---".  TeX will produce an em-dash
from it, while makeinfo will output two dashes.  Two dashes in Texinfo
will produce one dash in Info and something shorter that em-dash in
print.

> + id.  Each checkpoint will have a unique process id (or @var{pid}), 
> + and each will be different from the program's original @var{pid}.
> + If your program has saved a local copy of its process id, this could
> + potentially pose a problem.

Yes, this is a nasty limitation.  I think we should at least index it
(something like "@cindex checkpoints and process id").  Perhaps in the
future we should add a user command that would tell GDB the
variable(s) that hold the PID, so that GDB will automatically update
them with the new PID when the program is restarted at a checkpoint.

We should also tell users that `fork' must be compiled and linked into
the program, or else checkpointing will not work, right?

Also, I think these features should be mentioned in NEWS.

Finally, it would be nice to have a short description of the Linux
implementation of these two features in gdbint.texinfo.

Thanks again for working on this.