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

Eli Zaretskii
2005-12-09T14:22:29Z

> 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.