[m-rev.] for review: cleaning up and documenting I/O tabling

[Zoltan Somogyi]

On 18-Oct-2002, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> Were you planning on committing this before or after we branch for the
> new release?

Before. It doesn't really add new functionality, just makes existing
functionality usable.

> The new command "table_io allow" is not documented (not even in the
> "developer only" section), except in the CVS log message.  It should be,
> IMHO.  It could be either documented as a "developer only" option in the
> user guide, or with the documentation in the user guide commented out,
> or even just as a comment in the source code which implements it; but
> "this is for developers only" is not sufficient documentation, IMHO.

Ok, I added commented out documentation next to the other uses of "table_io"
in user_guide.texi, and in the source code.

> If you are deliberately omitting that from the list for command-line
> completion because it is not documented, then I think it should at
> least be mentioned in a comment here.

Done.

> It would be much nicer if this section started with a short paragraph
> summarizing the nature and purpose of I/O tabling.  Readers will be
> skimming through this manual; they shouldn't have to read through two
> long paragraphs of definitions before they get to the bit which tells
> them what the option does.

That's what I started to write originally. I couldn't write a paragraph
that was both accurate enough and clear enough unless I preceded it with
other prose setting the stage and giving definitions. Without those
definitions, you *cannot* explain what I/O tabling does.

> There's also a problem with ordering here.  This section occurs before
> the documentation of the "retry" command.  At very least there should
> be a cross-reference to the documentation for the "retry" command here.

Done.

> But I think it would be better to also move this section to after the
> "Debugger commands" section, and to add a forward reference to it
> from the documentation of the retry command.

I think that would make the problem worse.

I think the best solution would be to add an entry on "retry" in the debugger
concepts section, just before the section on I/O tabling. I'll do that as a
separate change.

> > +#ifdef	MR_REQUIRE_TRACING
> > +MR_bool			MR_io_tabling_allowed = MR_TRUE;
> > +#else
> > +MR_bool			MR_io_tabling_allowed = MR_FALSE;
> > +#endif
> 
> Both occurrences of "MR_bool" should be intended two spaces.

Done.

Zoltan.

diff -u doc/user_guide.texi doc/user_guide.texi
--- doc/user_guide.texi
+++ doc/user_guide.texi
@@ -1989,6 +1989,10 @@
 with the @samp{table_io start} command in mdb.
 
 The purpose of I/O tabling is to enable transparent retries across I/O actions.
+(The mdb @samp{retry} command
+restores the computation to a state it had earlier,
+allowing the programmer to explore code that the program has already executed;
+see its documentation in the Debugger commands section below.)
 In the absence of I/O tabling,
 retries across I/O actions can have bad consequences.
 Retry of a goal that reads some input requires that input to be provided twice;
@@ -2329,7 +2333,6 @@
 @table @code
 @item retry [-f]
 @kindex retry (mdb command)
-If
 Restarts execution at the call port
 of the call corresponding to the current event.
 @sp 1
@@ -2366,15 +2369,17 @@
 @c is not also in the repeated code
 @c may cause later file open actions to fail due to file descriptor leak.
 @c @end itemize
- at sp 1
-The debugger can perform a retry only from an exit or fail port;
-only at these ports does the debugger have enough information
-to figure out how to reset the stacks.
-If the debugger is not at such a port when a retry command is given,
-the debugger will continue forward execution
-until it reaches an exit or fail port of the call to be retried
-before it performs the retry.
-This may require a noticeable amount of time.
+ at c @sp 1
+ at c XXX the following limitation applies only in minimal model grades,
+ at c which are not officially supported:
+ at c The debugger can perform a retry only from an exit or fail port;
+ at c only at these ports does the debugger have enough information
+ at c to figure out how to reset the stacks.
+ at c If the debugger is not at such a port when a retry command is given,
+ at c the debugger will continue forward execution
+ at c until it reaches an exit or fail port of the call to be retried
+ at c before it performs the retry.
+ at c This may require a noticeable amount of time.
 @c XXX not yet
 @c and may result in the execution of I/O and/or other side-effects.
 @sp 1
@@ -2886,6 +2891,12 @@
 @sp 1
 @item table_io stats
 Reports statistics about I/O tabling.
+ at c "table_io allow" is not documented because its use by a non-expert
+ at c can yield weird results.
+ at c @sp 1
+ at c @item table_io allow
+ at c Allow I/O tabling to be started, even in grades in which
+ at c not all I/O primitives are guaranteed to be tabled.
 @end table
 
 @sp 1
diff -u runtime/mercury_trace_base.c runtime/mercury_trace_base.c
--- runtime/mercury_trace_base.c
+++ runtime/mercury_trace_base.c
@@ -66,19 +66,19 @@
 MR_bool			MR_io_tabling_debug = MR_FALSE;
 
 #ifdef	MR_REQUIRE_TRACING
-MR_bool			MR_io_tabling_allowed = MR_TRUE;
+  MR_bool		MR_io_tabling_allowed = MR_TRUE;
 #else
-MR_bool			MR_io_tabling_allowed = MR_FALSE;
+  MR_bool		MR_io_tabling_allowed = MR_FALSE;
 #endif
 
 #ifdef	MR_TRACE_HISTOGRAM
 
-int		*MR_trace_histogram_all = NULL;
-int		*MR_trace_histogram_exp = NULL;
-int		MR_trace_histogram_max  = 0;
-int		MR_trace_histogram_hwm  = 0;
+  int		*MR_trace_histogram_all = NULL;
+  int		*MR_trace_histogram_exp = NULL;
+  int		MR_trace_histogram_max  = 0;
+  int		MR_trace_histogram_hwm  = 0;
 
-#define	MR_TRACE_HISTOGRAM_FILENAME	".mercury_histogram"
+  #define	MR_TRACE_HISTOGRAM_FILENAME	".mercury_histogram"
 
 #endif
 
diff -u trace/mercury_trace_internal.c trace/mercury_trace_internal.c
--- trace/mercury_trace_internal.c
+++ trace/mercury_trace_internal.c
@@ -3252,7 +3252,15 @@
 		MR_print_unsigned_var(MR_mdb_out, "end",
 			MR_io_tabling_end);
 	} else if (word_count == 2 && MR_streq(words[1], "allow")) {
-		/* The  "table_io allow" command is for developers only */
+		/*
+		** The "table_io allow" command allows the programmer to give
+		** the command "table_io start" even in grades in which there
+		** is no guarantee that all I/O primitives are tabled. It is
+		** for developers only, because its use on programs in which
+		** some but not all I/O primitives are tabled, the results of
+		** turning on I/O tabling can be weird.
+		*/
+
 		MR_io_tabling_allowed = MR_TRUE;
 	} else {
 		MR_trace_usage("developer", "table_io");
@@ -5029,6 +5037,11 @@
 static const char *const	MR_trace_scope_cmd_args[] =
 		{"all", "interface", "entry", NULL};
 
+/*
+** "table_io allow" is deliberately not documented as it is developer only
+** "table_io begin" and "table_io end" are deliberately not documented in an
+** effort to encourage consistent use of start/stop.
+*/
 static const char *const	MR_trace_table_io_cmd_args[] =
 		{"stats", "start", "stop", NULL};
 
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------