clean up and fix GC message 0x1 (#9949)

Changes

@@ -140,6 +140,10 @@ Working version
   needed as the pagetable heads towards retirement).
   (David Allsopp, review by Xavier Leroy)
 
+- #9949: Clarify documentation of GC message 0x1 and make sure it is
+  displayed every time a major cycle is forcibly finished.
+  (Damien Doligez, review by Xavier Leroy)
+
 - #9951: Ensure that the mark stack push optimisation handles naked pointers
   (KC Sivaramakrishnan, reported by Enguerrand Decorne, review by Gabriel
    Scherer, and Xavier Leroy)

man/ocamlrun.m

@@ -211,7 +211,7 @@ What GC messages to print to stderr.  This is a sum of values selected
 from the following:
 
 .B 0x001
-Start of major GC cycle.
+Start and end of major GC cycle.
 
 .B 0x002
 Minor collection and major GC slice.

manual/manual/cmds/runtime.etex

@@ -145,7 +145,7 @@ The following environment variables are also consulted:
   \item[v] ("verbose")  What GC messages to print to stderr.  This
   is a sum of values selected from the following:
   \begin{options}
-        \item[1   (= 0x001)] Start of major GC cycle.
+        \item[1   (= 0x001)] Start and end of major GC cycle.
         \item[2   (= 0x002)] Minor collection and major GC slice.
         \item[4   (= 0x004)] Growing and shrinking of the heap.
         \item[8   (= 0x008)] Resizing of stacks and memory manager tables.

runtime/compact.c

@@ -504,6 +504,8 @@ void caml_compact_heap_maybe (void)
   if (fp >= caml_percent_max){
     caml_gc_message (0x200, "Automatic compaction triggered.\n");
     caml_empty_minor_heap ();  /* minor heap must be empty for compaction */
+    caml_gc_message
+      (0x1, "Finishing major GC cycle (triggered by compaction)\n");
     caml_finish_major_cycle ();
     ++ Caml_state->stat_forced_major_collections;
 

runtime/gc_ctrl.c

@@ -506,6 +506,7 @@ CAMLprim value caml_gc_set(value v)
   newpolicy = Long_val (Field (v, 6));
   if (newpolicy != caml_allocation_policy){
     caml_empty_minor_heap ();
+    caml_gc_message (0x1, "Full major GC cycle (changing allocation policy)\n");
     caml_finish_major_cycle ();
     caml_finish_major_cycle ();
     ++ Caml_state->stat_forced_major_collections;
@@ -563,7 +564,7 @@ CAMLprim value caml_gc_major(value v)
 
   CAML_EV_BEGIN(EV_EXPLICIT_GC_MAJOR);
   CAMLassert (v == Val_unit);
-  caml_gc_message (0x1, "Major GC cycle requested\n");
+  caml_gc_message (0x1, "Finishing major GC cycle (requested by user)\n");
   caml_empty_minor_heap ();
   caml_finish_major_cycle ();
   test_and_compact ();
@@ -580,7 +581,7 @@ CAMLprim value caml_gc_full_major(value v)
 
   CAML_EV_BEGIN(EV_EXPLICIT_GC_FULL_MAJOR);
   CAMLassert (v == Val_unit);
-  caml_gc_message (0x1, "Full major GC cycle requested\n");
+  caml_gc_message (0x1, "Full major GC cycle (requested by user)\n");
   caml_empty_minor_heap ();
   caml_finish_major_cycle ();
   // call finalisers
@@ -617,6 +618,7 @@ CAMLprim value caml_gc_compaction(value v)
   CAMLassert (v == Val_unit);
   caml_gc_message (0x10, "Heap compaction requested\n");
   caml_empty_minor_heap ();
+  caml_gc_message (0x1, "Full major GC cycle (compaction)\n");
   caml_finish_major_cycle ();
   // call finalisers
   exn = caml_process_pending_actions_exn();

runtime/major_gc.c

@@ -1076,6 +1076,7 @@ void caml_finalise_heap (void)
 {
   /* Finishing major cycle (all values become white) */
   caml_empty_minor_heap ();
+  caml_gc_message (0x1, "Finishing major GC cycle (finalising heap)\n");
   caml_finish_major_cycle ();
   CAMLassert (caml_gc_phase == Phase_idle);
 

stdlib/gc.mli

@@ -115,7 +115,7 @@ type control =
     (** This value controls the GC messages on standard error output.
        It is a sum of some of the following flags, to print messages
        on the corresponding events:
-       - [0x001] Start of major GC cycle.
+       - [0x001] Start and end of major GC cycle.
        - [0x002] Minor collection and major GC slice.
        - [0x004] Growing and shrinking of the heap.
        - [0x008] Resizing of stacks and memory manager tables.