Comments reformatting in mark.c to properly delimit sentences

(code refactoring)

* mark.c (GC_clear_hdr_marks, clear_marks_for_block, GC_set_mark_bit,
GC_clear_marks, GC_initiate_gc, GC_mark_from, alloc_mark_stack,
GC_push_all, GC_push_all_eager, GC_push_marked1, GC_push_marked2,
GC_push_marked4): Add training dot to comment sentences (where missing);
capitalize the first letter of comment sentences (where needed);
reformat some comments.
* mark.c [WRAP_MARK_SOME] (GC_mark_some): Likewise.
* mark.c [PARALLEL_MARK] (GC_do_parallel_mark, GC_help_wanted,
GC_helper_count, GC_active_count, GC_steal_mark_stack, GC_mark_local):
Likewise.
* mark.c [!GC_DISABLE_INCREMENTAL] (GC_push_next_marked_dirty):
Likewise.

diff --git a/mark.c b/mark.c
index 1812b94..4179062 100644 (file)
--- a/mark.c
+++ b/mark.c
@@ -130,7 +130,7 @@ GC_INNER GC_bool GC_collection_in_progress(void)
     return(GC_mark_state != MS_NONE);
 }
 
-/* clear all mark bits in the header */
+/* Clear all mark bits in the header.   */
 GC_INNER void GC_clear_hdr_marks(hdr *hhdr)
 {
   size_t last_bit;
@@ -171,9 +171,7 @@ GC_INNER void GC_set_hdr_marks(hdr *hhdr)
 #   endif
 }
 
-/*
- * Clear all mark bits associated with block h.
- */
+/* Clear all mark bits associated with block h. */
 static void clear_marks_for_block(struct hblk *h, word dummy GC_ATTR_UNUSED)
 {
     hdr * hhdr = HDR(h);
@@ -185,7 +183,7 @@ static void clear_marks_for_block(struct hblk *h, word dummy GC_ATTR_UNUSED)
     GC_clear_hdr_marks(hhdr);
 }
 
-/* Slow but general routines for setting/clearing/asking about mark bits */
+/* Slow but general routines for setting/clearing/asking about mark bits. */
 GC_API void GC_CALL GC_set_mark_bit(const void *p)
 {
     struct hblk *h = HBLKPTR(p);
@@ -231,11 +229,9 @@ GC_API int GC_CALL GC_is_marked(const void *p)
     return (int)mark_bit_from_hdr(hhdr, bit_no); /* 0 or 1 */
 }
 
-/*
- * Clear mark bits in all allocated heap blocks.  This invalidates
- * the marker invariant, and sets GC_mark_state to reflect this.
- * (This implicitly starts marking to reestablish the invariant.)
- */
+/* Clear mark bits in all allocated heap blocks.  This invalidates the  */
+/* marker invariant, and sets GC_mark_state to reflect this.  (This     */
+/* implicitly starts marking to reestablish the invariant.)             */
 GC_INNER void GC_clear_marks(void)
 {
     GC_apply_to_all_blocks(clear_marks_for_block, (word)0);
@@ -264,13 +260,12 @@ GC_INNER void GC_initiate_gc(void)
         GC_mark_state = MS_PUSH_RESCUERS;
     } else if (GC_mark_state != MS_INVALID) {
         ABORT("Unexpected state");
-    } /* else this is really a full collection, and mark        */
-      /* bits are invalid.                                      */
+    } /* Else this is really a full collection, and mark bits are invalid. */
     scan_ptr = 0;
 }
 
 #ifdef PARALLEL_MARK
-    STATIC void GC_do_parallel_mark(void); /* initiate parallel marking. */
+    STATIC void GC_do_parallel_mark(void); /* Initiate parallel marking. */
 #endif /* PARALLEL_MARK */
 
 #ifdef GC_DISABLE_INCREMENTAL
@@ -538,7 +533,7 @@ static void alloc_mark_stack(size_t);
           goto handle_ex;
 #     endif
     rm_handler:
-      /* Uninstall the exception handler */
+      /* Uninstall the exception handler.       */
       __asm__ __volatile__ ("mov %0, %%fs:0" : : "r" (er.ex_reg.prev));
       return ret_val;
 
@@ -630,7 +625,7 @@ GC_ATTR_NO_SANITIZE_ADDR GC_ATTR_NO_SANITIZE_MEMORY GC_ATTR_NO_SANITIZE_THREAD
 GC_INNER mse * GC_mark_from(mse *mark_stack_top, mse *mark_stack,
                             mse *mark_stack_limit)
 {
-  signed_word credit = HBLKSIZE;  /* Remaining credit for marking work  */
+  signed_word credit = HBLKSIZE;  /* Remaining credit for marking work. */
   ptr_t current_p;      /* Pointer to current candidate ptr.            */
   word current;         /* Candidate pointer.                           */
   ptr_t limit = 0;      /* (Incl) limit of current candidate range.     */
@@ -643,7 +638,7 @@ GC_INNER mse * GC_mark_from(mse *mark_stack_top, mse *mark_stack,
 
   GC_objects_are_marked = TRUE;
   INIT_HDR_CACHE;
-# ifdef OS2 /* Use untweaked version to circumvent compiler problem */
+# ifdef OS2 /* Use untweaked version to circumvent compiler problem.    */
     while ((word)mark_stack_top >= (word)mark_stack && credit >= 0)
 # else
     while (((((word)mark_stack_top - (word)mark_stack) | (word)credit)
@@ -653,8 +648,8 @@ GC_INNER mse * GC_mark_from(mse *mark_stack_top, mse *mark_stack,
     current_p = mark_stack_top -> mse_start;
     descr = mark_stack_top -> mse_descr.w;
   retry:
-    /* current_p and descr describe the current object.         */
-    /* *mark_stack_top is vacant.                               */
+    /* current_p and descr describe the current object.                 */
+    /* (*mark_stack_top) is vacant.                                     */
     /* The following is 0 only for small objects described by a simple  */
     /* length descriptor.  For many applications this is the common     */
     /* case, so we try to detect it quickly.                            */
@@ -680,7 +675,7 @@ GC_INNER mse * GC_mark_from(mse *mark_stack_top, mse *mark_stack,
 
               mark_stack_top -> mse_start = current_p;
               mark_stack_top -> mse_descr.w = new_size + sizeof(word);
-                                        /* makes sure we handle         */
+                                        /* Makes sure we handle         */
                                         /* misaligned pointers.         */
               mark_stack_top++;
 #             ifdef ENABLE_TRACE
@@ -789,13 +784,14 @@ GC_INNER mse * GC_mark_from(mse *mark_stack_top, mse *mark_stack,
           }
           if (0 == descr) {
               /* Can happen either because we generated a 0 descriptor  */
-              /* or we saw a pointer to a free object.          */
+              /* or we saw a pointer to a free object.                  */
               mark_stack_top--;
               continue;
           }
           goto retry;
       }
-    } else /* Small object with length descriptor */ {
+    } else {
+      /* Small object with length descriptor.   */
       mark_stack_top--;
 #     ifndef SMALL_CONFIG
         if (descr < sizeof(word))
@@ -897,11 +893,11 @@ GC_INNER mse * GC_mark_from(mse *mark_stack_top, mse *mark_stack,
 
 #ifdef PARALLEL_MARK
 
-STATIC GC_bool GC_help_wanted = FALSE;  /* Protected by mark lock       */
+STATIC GC_bool GC_help_wanted = FALSE;  /* Protected by mark lock.      */
 STATIC unsigned GC_helper_count = 0;    /* Number of running helpers.   */
-                                        /* Protected by mark lock       */
+                                        /* Protected by mark lock.      */
 STATIC unsigned GC_active_count = 0;    /* Number of active helpers.    */
-                                        /* Protected by mark lock       */
+                                        /* Protected by mark lock.      */
                                         /* May increase and decrease    */
                                         /* within each mark cycle.  But */
                                         /* once it returns to 0, it     */
@@ -959,7 +955,7 @@ GC_INNER void GC_wait_for_markers_init(void)
 /* Steal mark stack entries starting at mse low into mark stack local   */
 /* until we either steal mse high, or we have max entries.              */
 /* Return a pointer to the top of the local mark stack.                 */
-/* *next is replaced by a pointer to the next unscanned mark stack      */
+/* (*next) is replaced by a pointer to the next unscanned mark stack    */
 /* entry.                                                               */
 STATIC mse * GC_steal_mark_stack(mse * low, mse * high, mse * local,
                                  unsigned max, mse **next)
@@ -1138,7 +1134,7 @@ STATIC void GC_mark_local(mse *local_mark_stack, int id)
             if (0 == n_on_stack) {
                 GC_active_count--;
                 GC_ASSERT(GC_active_count <= GC_helper_count);
-                /* Other markers may redeposit objects  */
+                /* Other markers may redeposit objects          */
                 /* on the stack.                                */
                 if (0 == GC_active_count) GC_notify_all_marker();
                 while (GC_active_count > 0
@@ -1165,7 +1161,7 @@ STATIC void GC_mark_local(mse *local_mark_stack, int id)
                     if (need_to_notify) GC_notify_all_marker();
                     return;
                 }
-                /* else there's something on the stack again, or        */
+                /* Else there's something on the stack again, or        */
                 /* another helper may push something.                   */
                 GC_active_count++;
                 GC_ASSERT(GC_active_count > 0);
@@ -1216,7 +1212,7 @@ STATIC void GC_do_parallel_mark(void)
     while (GC_helper_count > 0) {
       GC_wait_marker();
     }
-    /* GC_helper_count cannot be incremented while GC_help_wanted == FALSE */
+    /* GC_helper_count cannot be incremented while not GC_help_wanted.  */
     GC_VERBOSE_LOG_PRINTF("Finished marking for mark phase number %lu\n",
                           (unsigned long)GC_mark_no);
     GC_mark_no++;
@@ -1296,7 +1292,7 @@ static void alloc_mark_stack(size_t n)
     if (GC_mark_stack != NULL) {
         if (new_stack != 0) {
           if (recycle_old) {
-            /* Recycle old space */
+            /* Recycle old space.       */
             GC_scratch_recycle_inner(GC_mark_stack,
                         GC_mark_stack_size * sizeof(struct GC_ms_entry));
           }
@@ -1392,7 +1388,7 @@ GC_API void GC_CALL GC_push_all(void *bottom, void *top)
         if ((*dirty_fn)(h)) {
             if ((word)(GC_mark_stack_top - GC_mark_stack)
                 > 3 * GC_mark_stack_size / 4) {
-                /* Danger of mark stack overflow */
+                /* Danger of mark stack overflow.       */
                 GC_push_all(h, top);
                 return;
             } else {
@@ -1563,11 +1559,8 @@ GC_API void GC_CALL GC_print_trace(word gc_no)
 
 #endif /* TRACE_BUF */
 
-/*
- * A version of GC_push_all that treats all interior pointers as valid
- * and scans the entire region immediately, in case the contents
- * change.
- */
+/* A version of GC_push_all that treats all interior pointers as valid  */
+/* and scans the entire region immediately, in case the contents change.*/
 GC_ATTR_NO_SANITIZE_ADDR GC_ATTR_NO_SANITIZE_MEMORY GC_ATTR_NO_SANITIZE_THREAD
 GC_API void GC_CALL GC_push_all_eager(void *bottom, void *top)
 {
@@ -1581,8 +1574,8 @@ GC_API void GC_CALL GC_push_all_eager(void *bottom, void *top)
 #   define GC_least_plausible_heap_addr least_ha
 
     if (top == 0) return;
-    /* check all pointers in range and push if they appear      */
-    /* to be valid.                                             */
+
+    /* Check all pointers in range and push if they appear to be valid. */
       lim = t - 1 /* longword */;
       for (p = b; (word)p <= (word)lim;
            p = (word *)(((ptr_t)p) + ALIGNMENT)) {
@@ -1703,7 +1696,7 @@ STATIC void GC_push_marked1(struct hblk *h, hdr *hhdr)
     p = (word *)(h->hb_body);
     plim = (word *)(((word)h) + HBLKSIZE);
 
-    /* go through all words in block */
+    /* Go through all words in block.   */
         while ((word)p < (word)plim) {
             word mark_word = *mark_word_addr++;
             word *q = p;
@@ -1753,7 +1746,7 @@ STATIC void GC_push_marked2(struct hblk *h, hdr *hhdr)
     p = (word *)(h->hb_body);
     plim = (word *)(((word)h) + HBLKSIZE);
 
-    /* go through all words in block */
+    /* Go through all words in block.   */
         while ((word)p < (word)plim) {
             word mark_word = *mark_word_addr++;
             word *q = p;
@@ -1804,7 +1797,7 @@ STATIC void GC_push_marked4(struct hblk *h, hdr *hhdr)
     p = (word *)(h->hb_body);
     plim = (word *)(((word)h) + HBLKSIZE);
 
-    /* go through all words in block */
+    /* Go through all words in block.   */
         while ((word)p < (word)plim) {
             word mark_word = *mark_word_addr++;
             word *q = p;
@@ -1836,7 +1829,7 @@ STATIC void GC_push_marked4(struct hblk *h, hdr *hhdr)
 
 #endif /* USE_PUSH_MARKED_ACCELERATORS */
 
-/* Push all objects reachable from marked objects in the given block */
+/* Push all objects reachable from marked objects in the given block.   */
 STATIC void GC_push_marked(struct hblk *h, hdr *hhdr)
 {
     word sz = hhdr -> hb_sz;
@@ -1896,7 +1889,6 @@ STATIC void GC_push_marked(struct hblk *h, hdr *hhdr)
 /* Unconditionally mark from all objects which have not been reclaimed. */
 /* This is useful in order to retain pointers which are reachable from  */
 /* the disclaim notifiers.                                              */
-/*                                                                      */
 /* To determine whether an object has been reclaimed, we require that   */
 /* any live object has a non-zero as one of the two lowest bits of the  */
 /* first word.  On the other hand, a reclaimed object is a members of   */
@@ -1971,7 +1963,7 @@ STATIC struct hblk * GC_push_next_marked(struct hblk *h)
 }
 
 #ifndef GC_DISABLE_INCREMENTAL
-  /* Identical to above, but mark only from dirty pages   */
+  /* Identical to above, but mark only from dirty pages.        */
   STATIC struct hblk * GC_push_next_marked_dirty(struct hblk *h)
   {
     hdr * hhdr = HDR(h);