[m-dev.] diff: documentation for trailing interface

[Fergus Henderson]

Peter Schachte, you wrote:
> >Trailing is a means
> > +of having side-effects such as destructive updates to data structures
> > +undone on backtracking.
> 
> Not to be pedantic, but I think this sentence would be more readable with a
> couple of commas:

Hey, pedantic is fine ;-)
Thanks for your detailed comments.

> > +A "choice point" is a point in the computation to
> > +which execution might backtrack.  The "current"
> > +choice point is the one that was most recently
> > +encountered; that is also the one to which execution
> > +will branch if the current computation fails.
> 
> `Encountered' is not very well defined.  Could you say `created' instead?

I was trying to avoid talking about "creating" choice points, since
the Mercury execution model doesn't have a choice point stack --
choice points are not physical entities.  Instead, I defined a choice
point as a point in the computation.

> Neither is actually correct, because after a failure, the choicepoint you
> would fail back to on failure will not be the most recent one `created' *or*
> `encountered.'  If you want to be accurate, maybe you could say
> 
> 	The "current" choice point is the one that was most recently created
> 	but not yet failed back into or committed to.  This is also ....
> 
> But then, of course, you'd need to define `failed back into' and `committed
> to'. 

Hmm.  How about just this:

	A "choice point" is a point in the computation to
	which execution might backtrack.  The "current"
	choice point is the one to which execution
	will branch if the current computation fails.

?

> > +the trail entries for those updates will be discarded;
> > +any updates occurring after that choice point will not be undone.
> 
> s/occurring after that choice point/made since that choice point was created/

As mentioned above I wanted to avoid talking about "creating" choice points.

> s/"prune"/``prune''/

Oh, thanks.  I found lots of other occurrences of that bug.
Also a few `--' that should have been `---'.

> > +Execution may subsequently backtrack to a @emph{prior} choice point,
> > +but if so, the values updated will not be live at that point, so
> > +there is no need to undo the updates.
> 
> An explaination of why this is true would be helpful.

But is not easy ;-)
I'll have a go.

Hmm...  I think maybe the reason that an explanation of why it is true
is that it is in fact not true :-(

> Note that your description of the MR_gc reason here is not in keeping with
> the latest thinking (I've heard) on this.

Ah, yeah, I screwed that one up.  I'll fix it.

> > +... instead, it is
> > +enough to record the original state of each updated data structure
> > +just once for each choice point, rather than once for each update.
> 
> s/choice point,/choice point created after the data structure is allocated,/

OK, but s/created/occurring/

-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.