[m-rev.] For review: allow declarative debugger to search upward from initial symptom

[Ian MacLarty]

On Fri, Dec 03, 2004 at 12:48:34AM +1100, Julien Fischer wrote:
> > Index: doc/user_guide.texi
> > ===================================================================
> > RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
> > retrieving revision 1.398
> > diff -u -r1.398 user_guide.texi
> > --- doc/user_guide.texi	19 Nov 2004 11:54:21 -0000	1.398
> > +++ doc/user_guide.texi	29 Nov 2004 09:30:27 -0000
> > @@ -3215,8 +3215,17 @@
> >  @c makes an assertion, and if the assertion is incorrect, the resulting
> >  @c behaviour would be hard for non-developers to understand. The option is
> >  @c therefore deliberately not documented.
> > -Starts declarative debugging
> > -using the current event as the initial symptom.
> > +Starts declarative debugging using the current event as the initial symptom.
> > + at sp 1
> > +The declarative debugger searches for bugs in a debug tree.  Only a portion of
> 
> Dropping in the term "debug tree" without any further explanation isn't so
> good - the rest of the documentation for the declarative debugger
> doesn't use the term.
> 
> > +the debug tree is materialized at any time to save memory.  When a new portion
> > +of the tree needs to be materialized the program being debugged is re-executed.
> 
> I think the concept of the tree being "materialized" needs further
> explanation.  Perhaps it would be better to say that the dd can only
> consider parts of the program at once and that it is the size of these
> parsts that the`--depth-step-size' option controls?
> 
I didn't want to go into too much detail about how the declarative debugger
works here.  I've changed the text to the following which avoids using the 
term "debug tree".  I think the concept of an "execution trace" should be
familiar to someone using the debugger.

When searching for bugs the declarative debugger needs to keep portions of the
execution trace in memory.  If it requires a new portion of the trace then it
needs to rerun the program.  The @samp{-d at var{depth}} and
@samp{--depth-step-size @var{depth}} options tell the declarative debugger how
much of the execution trace to gather when it reruns the program.  A higher
@var{depth} will require more memory, but will improve the performance of the
declarative debugger for long running programs since it will not have to rerun
the program as much.

> > +How much of the debug tree is materialized at any one time can be controlled
> > +with the @samp{-d at var{depth}} or @samp{--depth-step-size @var{depth}} option.
> > + at var{depth} is the maximum depth of any newly materialized portion of the debug
> > +tree.  A higher value of @var{depth} will mean more memory is used, but the
> 
> I suggest rewording that as "A higher value ... will mean that more ..."
> 
This has been replaced with the above.

> > +program will have to be re-executed less often.  Set a higher @var{depth} for
> > +long-running programs to improve the performance of the declarative debugger.
> 
> I don't think that this last sentence is necessary - the performance
> ramifications should be obvious from the sentence before.
> 
See above.

> >  @item quit [-y]
> >  @kindex quit (mdb command)
> > @@ -3900,6 +3906,15 @@
> >  If, say, the date was only wrong in the year part, then we could also have
> >  marked the year subterm in which case the next question would have been about
> >  the call that constructed the year part of the date.
> > +
> > +This feature is also useful when using the procedural debugger.  Suppose you
> > +come accross a CALL event and you'd like to know where a particular input
> s/accross/across/
> s/you'd/you would/
> 
> I suggest rewording that sentence as:
> 
> For example, suppose that you come across a CALL event and you would like to know
> the source of a particular input to the call.
> 
Okay.
> > +to the call came from.  To find out you could first go to the final event by
> 
> I'd change "could" to "would" there unless there is another way of doing
> it.
> 
Well you could just look for it manually...

> > +issuing a @samp{finish} command.  Then invoke the declarative debugger with
> > +a @samp{dd} command.  Then mark the input term you're interested in.
> 
> How about:
> 
> Invoke the declarative debugger with a @samp{dd} command and then mark
> the input term you are interested in.
> 
That's better, thanks.

> > The
> > +next question should be about the call that bound the term at which point you
> s/should/will/?
> > +could issue a @samp{pd} command to return to the procedural debugger at the
> > +final event of the call that bound the term.
> >
> It seems like two sentences have run into each other there.  I suggest
> splitting that sentence up.
> 
I've changes it to:

The next question should be about the call that bound the term.  Issue a
@samp{pd} command at this point to return to the procedural debugger at the
final event of the call that bound the term.

Cheers,
Ian.

--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------