Some changes to make GC_dump() a little more useful.

gc_dump() will now print a label for the dump if one is given, if none is
given then a label is created using the current gc major collection number.
This makes it easier to work with multiple dumps in a single file.

In each dump write the elapsed mutator time.  This will make plotting heap
changes over time possible.

include/gc.h:
    GC_dump() now takes an argument used to "label" the dump.  Making it
    easier to create and use multiple dumps.

misc.c:
    gc_dump() will now print a label for the dump if one is given, if none
    is given then a label is created using the current gc major collection
    number.

    in the dump write the elapsed mutator time.  this is calculated by
    subtracting the current time from gc_init_time (a new variable) and
    then subtracting the time spent collecting (gc_total_gc_time).

    If debugging support is compiled in, then set GC_calc_gc_time to 1 and
    record the time the GC was initialised, as this could be used by calls
    to GC_dump().

include/private/gc.h:
    Conform to GC_dump() change.

    Export GC_init_time variable.

alloc.c:
    Add GC_init_time variable.

alloc.c

@@ -68,6 +68,8 @@ GC_bool         GC_calc_gc_time = 0;
 			   /* GC_total_gc_time if set to true.  */
 unsigned long   GC_total_gc_time = 0;
 			   /* Measured in milliseconds.         */
+unsigned long   GC_init_time;
+                           /* The time that the GC was initialised. */
 
 #ifndef GC_DISABLE_INCREMENTAL
   GC_INNER int GC_incremental = 0;      /* By default, stop the world.  */

include/gc.h

@@ -1527,7 +1527,9 @@ GC_API void * GC_CALL GC_is_valid_displacement(void * /* p */);
 /* debugger, or by setting the GC_DUMP_REGULARLY environment variable,  */
 /* but it may be useful to call it from client code during debugging.   */
 /* Defined only if the library has been compiled without NO_DEBUGGING.  */
-GC_API void GC_CALL GC_dump(void);
+/* label may be a string to be used to help identifiy individual dumps, */
+/* if label is NULL the current GC number will be used.                 */
+GC_API void GC_CALL GC_dump(const char *label);
 
 /* Dump information about each block of every GC memory section.        */
 /* Defined only if the library has been compiled without NO_DEBUGGING.  */

include/private/gc_priv.h

@@ -2153,7 +2153,7 @@ void GC_print_block_list(void);
 void GC_print_hblkfreelist(void);
 void GC_print_heap_sects(void);
 void GC_print_static_roots(void);
-/* void GC_dump(void); - declared in gc.h */
+/* void GC_dump(const char *label); - declared in gc.h */
 
 extern word GC_fo_entries; /* should be visible in extra/MacOS.c */
 
@@ -2447,11 +2447,12 @@ GC_INNER ptr_t GC_store_debug_info(ptr_t p, word sz, const char *str,
 #ifndef NO_DEBUGGING
   GC_EXTERN GC_bool GC_dump_regularly;
                                 /* Generate regular debugging dumps.    */
-# define COND_DUMP if (EXPECT(GC_dump_regularly, FALSE)) GC_dump(); \
+# define COND_DUMP if (EXPECT(GC_dump_regularly, FALSE)) GC_dump(NULL); \
                         else COND_DUMP_CHECKS
 #else
 # define COND_DUMP COND_DUMP_CHECKS
 #endif
+GC_EXTERN unsigned long GC_init_time;
 
 #if defined(PARALLEL_MARK)
   /* We need additional synchronization facilities from the thread      */

misc.c

@@ -1003,6 +1003,13 @@ GC_API void GC_CALL GC_init(void)
           }
         }
 #     endif
+#     if !defined(NO_DEBUGGING)
+        /*
+         * The total mutator time is used with GC_dump.
+         */
+        GC_calc_gc_time = 1;
+        GET_TIME(GC_init_time);
+#     endif
 #   endif /* !SMALL_CONFIG */
 #   if !defined(NO_DEBUGGING) && !defined(GC_DUMP_REGULARLY)
       if (0 != GETENV("GC_DUMP_REGULARLY")) {
@@ -2054,9 +2061,21 @@ GC_API void * GC_CALL GC_do_blocking(GC_fn_type fn, void * client_data)
 }
 
 #if !defined(NO_DEBUGGING)
-  GC_API void GC_CALL GC_dump(void)
+  GC_API void GC_CALL GC_dump(const char *label)
   {
-    GC_printf("***Static roots:\n");
+    unsigned long mut_time;
+
+    if (NULL != label) {
+      GC_printf("***GC Dump %s\n", label);
+    } else {
+      GC_printf("***GC Dump collection %lu\n", GC_get_gc_no());
+    }
+
+    GET_TIME(mut_time);
+    mut_time -= GC_init_time + GC_total_gc_time;
+    GC_printf("Time: %lu\n", mut_time);
+
+    GC_printf("\n***Static roots:\n");
     GC_print_static_roots();
     GC_printf("\n***Heap sections:\n");
     GC_print_heap_sects();