[m-rev.] diff: make AGC debugging a run-time option

[Fergus Henderson]

On 06-Aug-2002, Zoltan Somogyi <zs at cs.mu.OZ.AU> wrote:
> On 02-Aug-2002, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> > Make the accurate GC debugging code a run-time option
> > rather than a compile-time option.
> > 
> > The run-time cost of this is very small -- just a few `if' statements
> > per garbage collection -- and it is more convenient if agc debugging
> > can be enabled by setting MERCURY_OPTIONS rather than by having to
> > recompile the Mercury runtime.
> 
> Actually, our policy has been for this kind of debugging code to be protected
> by *both* a #ifdef and a runtime test.

For debugging code which has a very low overhead and a high utility,
as is the case here, I think it is better to just use a runtime test.
And indeed that is what we have done in the past (e.g. with MR_memorydebug).
Using #ifdef is only justified if the time and/or space costs of
the debugging code are significant.

As a matter of ideal coding style, for code which has a higher overhead or
a lower utility, I think it is best to write the code using `if (...)',
and then have the variable declaration protected with #if, as shown in
the following example.


	/* some example code which does some foo debugging */
	#include "foo.h"
	void do_some_foo_stuff(void) {
		if (debug_foo()) printf("starting do_some_foo_stuff()\n");
		...
		if (debug_foo()) printf("finished do_some_foo_stuff()\n");
	}


	/* --- foo.h (or options.h) --- */
	#include "conf.h"
	#if DEBUG_FOO
	  extern bool debug_foo_option;
	  #define debug_foo() debug_foo_option
	#else
	  #define debug_foo() FALSE
	#endif


	/* --- foo.c (or options.c) --- */
	#include "conf.h"
	#if DEBUG_FOO
	bool debug_foo_option = FALSE;
	#endif


	/* --- options.c --- */
	#include "conf.h"
	/* this function is called if --debug-foo option is specified */
	static void enable_debug_foo(void) {
	    #if DEBUG_FOO
	      debug_foo_option = TRUE;
	    #else
	      error("--debug-foo only supported if compiled with -DDEBUG_FOO");
	    #endif
	}
	...
	void parse_options(int argc, char *argv) {
		...
		switch (...) {
		case DEBUG_FOO_OPT: enable_debug_foo();
		...
		}
	}

	/* --- conf.h --- */
	/* Define DEBUG_FOO to enable FOO debugging. */
	#ifndef DEBUG_FOO
	#define DEBUG_FOO 0
	#endif


This is somewhat different to the style that we have been using in the
Mercury implementation.  It has two advantages:

(1) It uses `if (...)' rather than `#ifdef' for the main debugging tests.

    This is useful because it ensures that the debugging code still
    gets type-checked, even when DEBUG_FOO is not defined.
    It is also more convenient than using both `#ifdef' and `if (...)'.

(2) It uses `#if' rather than `#ifdef' (except in conf.h).

    This is better because compilers can warn you if you misspell a name
    in `#if' (gcc does this with -Wundef), but they can't warn you if
    you misspell a name in `#ifdef'.

    (Note that although this example uses #ifdef in conf.h, 
    if you misspell the name in conf.h, then you'll still get warned;
    the warning(s) will occur in #if statements in the other files that
    reference the macro.)

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------