New API function (GC_dump_named) to produce named dumps

gc_dump() now prints a label (name) for the dump, by default the name
is created using the current garbage collection number (GC_get_gc_no).
An arbitrary name could be provided using GC_dump_named() instead.
The naming makes it easier to work with multiple dumps in a single log.

* include/gc.h (GC_dump_named): New public API function declaration.
* include/gc.h (GC_dump): Update comment (the current collection number
is printed at the beginning of the dump).
* misc.c [!NO_DEBUGGING] (GC_dump): Just call GC_dump_named(NULL).
* misc.c [!NO_DEBUGGING] (GC_dump_named): Move code from GC_dump;
start dump with the "GC Dump" followed by either the name specified or
the current collection number (if name is null).

diff --git a/include/gc.h b/include/gc.h
index 7846314..5c91636 100644 (file)
--- a/include/gc.h
+++ b/include/gc.h
@@ -1515,8 +1515,12 @@ GC_API void * GC_CALL GC_is_valid_displacement(void * /* p */);
 /* Explicitly dump the GC state.  This is most often called from the    */
 /* debugger, or by setting the GC_DUMP_REGULARLY environment variable,  */
 /* but it may be useful to call it from client code during debugging.   */
+/* If name is specified (and non-NULL), it is printed to help           */
+/* identifying individual dumps.  Otherwise the current collection      */
+/* number is used as the name.                                          */
 /* Defined only if the library has been compiled without NO_DEBUGGING.  */
-GC_API void GC_CALL GC_dump(void);
+GC_API void GC_CALL GC_dump_named(const char * /* name */);
+GC_API void GC_CALL GC_dump(void); /* = GC_dump_named(NULL) */
 
 /* Dump information about each block of every GC memory section.        */
 /* Defined only if the library has been compiled without NO_DEBUGGING.  */

diff --git a/misc.c b/misc.c
index a9b6a2b..8f04cda 100644 (file)
--- a/misc.c
+++ b/misc.c
@@ -2056,7 +2056,17 @@ 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_printf("***Static roots:\n");
+    GC_dump_named(NULL);
+  }
+
+  GC_API void GC_CALL GC_dump_named(const char *name)
+  {
+    if (name != NULL) {
+      GC_printf("***GC Dump %s\n", name);
+    } else {
+      GC_printf("***GC Dump collection #%lu\n", (unsigned long)GC_gc_no);
+    }
+    GC_printf("\n***Static roots:\n");
     GC_print_static_roots();
     GC_printf("\n***Heap sections:\n");
     GC_print_heap_sects();