Changes entry and comments for Safepoints (#10039)

(cherry picked from commit 1b3ffee)

Changes

@@ -7,8 +7,9 @@ OCaml 4.13.0
   Add poll points to native generated code. These are effectively
   zero-sized allocations and fix some signal and remembered set
   issues. Also multicore prerequisite.
-  (Sadiq Jaffer, Damien Doligez, Mark Shinwell, Anmol Sahoo, Stephen Dolan,
-  Xavier Leroy reviewed by ??)
+  (Sadiq Jaffer, Stephen Dolan, Damien Doligez, Xavier Leroy,
+   Anmol Sahoo, Mark Shinwell, review by Damien Doligez, Xavier Leroy,
+   and Mark Shinwell)
 
 - #9331: Improve error messages for functor application and functor types.
   (Florian Angeletti and Gabriel Radanne, review by Leo White)

asmcomp/polling.ml

@@ -92,7 +92,37 @@ let polled_loops_analysis funbody =
    that does not go through an Ialloc or Ipoll instruction.
 
    "Always_polls", therefore, means the function always polls (via Ialloc or
-   Ipoll) before doing a PRTC.
+   Ipoll) before doing a PRTC.  This includes the case where it does not
+   perform any PRTC.
+
+   A note on Potentially Recursive Tail Calls
+   ------------------------------------------
+
+   Tail calls can create infinite loops, of course. (Consider a function
+   that tail-calls itself.)  But not all tail calls need to be flagged
+   as potential infinite loops.
+
+   We optimise by making a partial ordering over Mach functions: in
+   definition order within a compilation unit, and dependency
+   order between compilation units. This order is acyclic, as
+   OCaml does not allow circular dependencies between modules.
+   It's also finite, so if there's an infinite sequence of
+   function calls then something has to make a forward reference.
+
+   Also, in such an infinite sequence of function calls, at most finitely
+   many of them can be non-tail calls. (If there are infinitely many
+   non-tail calls, then the program soon terminates with a stack
+   overflow).
+
+   So, every such infinite sequence must contain many forward-referencing
+   tail calls.  These tail calls are the Potentially Recursive Tail Calls
+   (PTRCs).  Polling only on those calls suffices.
+
+   Several functions below take a parameter [future_funcnames]
+   which is the set of functions defined "after" the current function
+   in the current compilation unit.  The PTRCs are tail calls
+   to known functions in [future_funcnames], or tail calls to
+   unknown functions.
 *)
 
 type polls_before_prtc = Might_not_poll | Always_polls
@@ -124,27 +154,12 @@ let potentially_recursive_tailcall ~future_funcnames funbody =
     match i.desc with
     | Iend -> next
     | Iop (Ialloc _ | Ipoll _) -> Always_polls
-    | Iop (Itailcall_ind) -> Might_not_poll
+    | Iop (Itailcall_ind) -> Might_not_poll  (* this is a PTRC *)
     | Iop (Itailcall_imm { func }) ->
-      (* We optimise by making a partial ordering over Mach functions: in
-         definition order within a compilation unit, and dependency order
-         between compilation units. This order is acyclic, as OCaml does not
-         allow circular dependencies between modules.  It's also finite, so if
-         there's an infinite sequence of function calls then something has to
-         make a forward reference.
-
-         Also, in such an infinite sequence of function calls, at most finitely
-         many of them can be non-tail calls. (If there are infinitely many
-         non-tail calls, then the program soon terminates with a stack
-         overflow).
-
-         So, every such infinite sequence must contain many forward-referencing
-         tail calls, so polling only on those suffices.  This is checked using
-         the set [future_funcnames]. *)
       if String.Set.mem func future_funcnames
          || function_is_assumed_to_never_poll func
-      then Might_not_poll
-      else Always_polls
+      then Might_not_poll  (* this is a PTRC *)
+      else Always_polls    (* this is not a PTRC *)
     | Iop op ->
       if operation_can_raise op
       then Polls_before_prtc.join next exn